Merge pull request #14 from aniongithub/refactor/strip-sse

Replace SSE with REST API for web UI

Author: aniongithub

README.md

@@ -4,26 +4,25 @@
 
 **A wiki for AI agents — and humans too.**
 
-`mind-map` is a wiki engine that stores pages as plain markdown files, indexes them with SQLite FTS5, and exposes everything via MCP over HTTP/SSE. AI agents and humans connect to the same server using the same protocol. One binary, zero runtime dependencies.
+`mind-map` is a wiki engine that stores pages as plain markdown files, indexes them with SQLite FTS5, and exposes them via MCP (for AI agents) and a REST API with web UI (for humans). One binary, zero runtime dependencies.
 
 ## The Problem
 
 AI agents need persistent, structured memory. Today that means:
 
-- 🔴 **Desktop apps** — tools like Tolaria require Node.js + Rust + WebKit + a display server just to give agents a knowledge base
-- 🔴 **Single-user** — stdio MCP is one agent, one pipe, that's it
-- 🔴 **No web access** — the knowledge is locked in a desktop app only the local user can see
-- 🔴 **Can't deploy headless** — needs a GUI environment even when no human is looking
+- **Desktop apps** -- tools like Tolaria require Node.js + Rust + WebKit + a display server just to give agents a knowledge base
+- **No web access** -- the knowledge is locked in a desktop app only the local user can see
+- **Can't deploy headless** -- needs a GUI environment even when no human is looking
 
 ## The Solution
 
-`mind-map` is a **server**, not an app. It runs anywhere — your laptop, a container or a cloud VM.
+`mind-map` is a **server**, not an app. It runs anywhere -- your laptop, a container or a cloud VM.
 
-1. **One protocol** — MCP over HTTP/SSE. The web UI and AI agents are both MCP clients
-2. **One binary** — Go, statically compiled, `curl | bash` to install
-3. **Plain markdown** — pages are `.md` files with YAML frontmatter. Git-friendly, portable, yours
-4. **Multi-agent** — HTTP/SSE means any number of agents can connect simultaneously
-5. **Built-in web UI** — browse, search, and edit the wiki from any browser
+1. **Agents use stdio** -- `mind-map` with no args starts an MCP server on stdin/stdout
+2. **Humans use the web UI** -- `mind-map serve` starts an HTTP server with REST API and browser UI
+3. **One binary** -- Go, statically compiled, `curl | bash` to install
+4. **Plain markdown** -- pages are `.md` files with YAML frontmatter. Git-friendly, portable, yours
+5. **Multi-process safe** -- SQLite page locking lets multiple agents share the same wiki directory
 
 ```
 Agent: "What do we know about authentication?"
@@ -52,28 +51,31 @@ Binaries available for **linux-x64**, **linux-arm64**, **darwin-x64**, **darwin-
 
 ```mermaid
 graph TD
-    A[Preact Web App] -->|MCP over HTTP/SSE| B
-    C[AI Agent] -->|MCP over HTTP/SSE| B
-    D[AI Agent] -->|MCP over stdio| B
+    A[Preact Web App] -->|REST API| B
+    C[AI Agent] -->|MCP stdio| D
 
     subgraph "mind-map serve"
-        B[MCP Server] --> E[Wiki Engine]
-        E --> F[SQLite FTS5]
+        B[HTTP Server] --> E[Wiki Engine]
     end
 
+    subgraph "mind-map (stdio)"
+        D[MCP Server] --> E
+    end
+
+    E --> F[SQLite FTS5]
     E -->|read/write| G[Markdown Files]
 ```
 
-The web UI is a static Preact app served from the same binary. It connects to the MCP SSE endpoint at `/mcp` — the same endpoint AI agents use. There is no separate REST API.
+The web UI is a static Preact app served by `mind-map serve`. It uses a REST API to read and write pages. AI agents use stdio MCP -- each agent launches its own `mind-map` process.
 
-## Two Modes, One Server
+## Two Modes
 
 | Mode | Command | Use case |
 |------|---------|----------|
-| **HTTP/SSE** (default) | `mind-map serve --dir ~/.mind-map/wiki` | Web UI + multiple agents |
-| **stdio** | `mind-map serve --stdio --dir ~/.mind-map/wiki` | Single agent (Copilot, Claude Desktop, Cursor) |
+| **stdio** (default) | `mind-map` | AI agents (Copilot, Claude, Cursor) |
+| **HTTP** | `mind-map serve` | Web UI for humans |
 
-Both modes use the same wiki engine, same MCP tools, same code path. The only difference is the transport.
+Both modes use the same wiki engine and the same wiki directory (`~/.mind-map/wiki` by default). Multiple stdio processes can safely share the same wiki via SQLite page locking.
 
 ## MCP Tools (8 total)
 
@@ -88,13 +90,16 @@ Both modes use the same wiki engine, same MCP tools, same code path. The only di
 | `list_pages` | List pages, optionally filtered by path prefix |
 | `get_backlinks` | Get all pages that link to a given page |
 
+| `register_sync` | Register a wiki path prefix to sync with a git remote |
+
 ## Wiki Features
 
-- **YAML frontmatter** — structured metadata on every page (`title`, `type`, `status`, custom fields)
-- **Wikilinks** — `[[target]]` and `[[display|target]]` syntax, resolved to clickable links
-- **Backlink index** — every page knows what links to it
-- **Full-text search** — SQLite FTS5 with ranked results and snippets
-- **Concurrent access** — `sync.RWMutex` for safe multi-agent reads and writes
+- **YAML frontmatter** -- structured metadata on every page (`title`, `type`, `status`, custom fields)
+- **Wikilinks** -- `[[target]]` and `[[display|target]]` syntax, resolved to clickable links
+- **Backlink index** -- every page knows what links to it
+- **Full-text search** -- SQLite FTS5 with ranked results and snippets
+- **Multi-process safe** -- SQLite page locking for concurrent agent access
+- **Git sync** -- sync wiki pages to GitHub repo wikis via configurable mappings
 
 ## Web UI
 
@@ -106,35 +111,21 @@ The built-in web UI is a metro-inspired, chromeless Preact app:
 - Edit mode with raw markdown editor
 - Dark / light theme toggle
 
-The web UI speaks MCP — it's an MCP client, not a separate interface. If an agent creates a page, it appears in the browser. If you edit in the browser, the agent sees the change.
-
-## MCP Server Configuration
+The web UI speaks the same language as the wiki engine. If an agent creates a page via stdio, it appears in the browser. If you edit in the browser, the agent sees the change on its next read.
 
-### Linux / macOS (stdio)
+## MCP Client Configuration
 
 ```json
 {
   "mcpServers": {
     "mind-map": {
-      "command": "mind-map",
-      "args": ["serve", "--stdio", "--dir", "~/.mind-map/wiki"]
+      "command": "mind-map"
     }
   }
 }
 ```
 
-### Windows
-
-```json
-{
-  "mcpServers": {
-    "mind-map": {
-      "command": "mind-map",
-      "args": ["serve", "--stdio"]
-    }
-  }
-}
-```
+That's it. No args needed -- stdio mode and `~/.mind-map/wiki` are the defaults. Override the directory with `--dir` if needed.
 
 ## Page Format
 

cmd/mind-map/main.go

@@ -20,28 +20,28 @@ import (
 	mindsync "github.com/aniongithub/mind-map/internal/sync"
 	"github.com/aniongithub/mind-map/webui"
 	"github.com/kardianos/service"
-	"github.com/modelcontextprotocol/go-sdk/mcp"
+	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/spf13/cobra"
 )
 
 var rootCmd = &cobra.Command{
 	Use:   "mind-map",
 	Short: "A wiki engine with MCP interface for AI agents",
-	Long:  "mind-map is a wiki that stores pages as markdown files, indexes them with SQLite FTS5, and exposes everything via MCP over HTTP/SSE. AI agents and humans use the same protocol.\n\nRunning without a subcommand starts the MCP server in stdio mode.",
+	Long:  "mind-map is a wiki that stores pages as markdown files, indexes them with SQLite FTS5, and exposes everything via MCP (stdio) or a REST API (serve). Agents use stdio, humans use the web UI.\n\nRunning without a subcommand starts the MCP server in stdio mode.",
 	RunE:  runStdio,
 }
 
 var serveCmd = &cobra.Command{
 	Use:   "serve",
-	Short: "Start the HTTP/SSE server with web UI",
-	Long:  "Starts the mind-map server in HTTP/SSE mode with the web UI. Use this for browser access and multi-agent setups.",
+	Short: "Start the HTTP server with web UI",
+	Long:  "Starts the mind-map HTTP server with REST API and web UI.",
 	RunE:  runServe,
 }
 
 func init() {
 	rootCmd.PersistentFlags().StringP("dir", "d", defaultWikiDir(), "Path to the wiki directory")
 
-	serveCmd.Flags().StringP("addr", "a", ":51849", "Address to listen on (HTTP/SSE mode)")
+	serveCmd.Flags().StringP("addr", "a", ":51849", "Address to listen on")
 	serveCmd.Flags().String("webui", "", "Path to webui dist directory (overrides embedded webui)")
 	serveCmd.Flags().String("log-file", "", "Path to log file (logs to stderr and file)")
 	serveCmd.Flags().Duration("idle-timeout", 60*time.Second, "Idle timeout for HTTP connections (e.g. 30s, 1m)")
@@ -62,7 +62,7 @@ func runStdio(cmd *cobra.Command, args []string) error {
 
 	s := mindmcp.NewServer(w, nil)
 	slog.Info("mind-map MCP server starting", slog.String("mode", "stdio"), slog.String("wiki", w.Root()))
-	return s.MCPServer().Run(cmd.Context(), &mcp.StdioTransport{})
+	return s.MCPServer().Run(cmd.Context(), &mcpsdk.StdioTransport{})
 }
 
 func runServe(cmd *cobra.Command, args []string) error {
@@ -88,7 +88,7 @@ func runServe(cmd *cobra.Command, args []string) error {
 		defer f.Close()
 	}
 
-	// HTTP/SSE mode
+	// HTTP mode
 	addr, _ := cmd.Flags().GetString("addr")
 	webuiDir, _ := cmd.Flags().GetString("webui")
 
@@ -108,7 +108,7 @@ func runServe(cmd *cobra.Command, args []string) error {
 	return runHTTPServer(addr, dir, webuiDir, idleTimeout, stopCh)
 }
 
-// runHTTPServer starts the HTTP/SSE server and blocks until stopCh is closed.
+// runHTTPServer starts the HTTP server and blocks until stopCh is closed.
 // Shared by both the interactive `serve` command and the system service.
 func runHTTPServer(addr, dir, webuiDir string, idleTimeout time.Duration, stopCh chan struct{}) error {
 	w, err := wiki.Open(dir)
@@ -139,12 +139,107 @@ func runHTTPServer(addr, dir, webuiDir string, idleTimeout time.Duration, stopCh
 		}
 	}
 
-	sseHandler := mcp.NewSSEHandler(func(r *http.Request) *mcp.Server {
-		return mindmcp.NewServer(w, gs).MCPServer()
-	}, nil)
-
+	// REST API for wiki operations (used by web UI)
 	mux := http.NewServeMux()
-	mux.Handle("/mcp", sseHandler)
+
+	mux.HandleFunc("GET /api/context", func(rw http.ResponseWriter, r *http.Request) {
+		wctx, err := w.Context(r.Context())
+		if err != nil {
+			http.Error(rw, err.Error(), http.StatusInternalServerError)
+			return
+		}
+		jsonResponse(rw, wctx)
+	})
+
+	mux.HandleFunc("GET /api/pages", func(rw http.ResponseWriter, r *http.Request) {
+		prefix := r.URL.Query().Get("prefix")
+		pages, err := w.ListPages(r.Context(), prefix)
+		if err != nil {
+			http.Error(rw, err.Error(), http.StatusInternalServerError)
+			return
+		}
+		jsonResponse(rw, pages)
+	})
+
+	mux.HandleFunc("GET /api/pages/{path...}", func(rw http.ResponseWriter, r *http.Request) {
+		pagePath := r.PathValue("path")
+		page, err := w.GetPage(r.Context(), pagePath)
+		if err != nil {
+			http.Error(rw, err.Error(), http.StatusNotFound)
+			return
+		}
+		jsonResponse(rw, page)
+	})
+
+	mux.HandleFunc("POST /api/pages", func(rw http.ResponseWriter, r *http.Request) {
+		var req struct {
+			Path    string `json:"path"`
+			Content string `json:"content"`
+		}
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			http.Error(rw, "invalid JSON: "+err.Error(), http.StatusBadRequest)
+			return
+		}
+		if req.Path == "" || req.Content == "" {
+			http.Error(rw, "path and content are required", http.StatusBadRequest)
+			return
+		}
+		if err := w.CreatePage(r.Context(), req.Path, req.Content); err != nil {
+			http.Error(rw, err.Error(), http.StatusConflict)
+			return
+		}
+		rw.WriteHeader(http.StatusCreated)
+		jsonResponse(rw, map[string]string{"status": "created", "path": req.Path})
+	})
+
+	mux.HandleFunc("PUT /api/pages/{path...}", func(rw http.ResponseWriter, r *http.Request) {
+		pagePath := r.PathValue("path")
+		var req struct {
+			Content string `json:"content"`
+		}
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			http.Error(rw, "invalid JSON: "+err.Error(), http.StatusBadRequest)
+			return
+		}
+		if err := w.UpdatePage(r.Context(), pagePath, req.Content); err != nil {
+			http.Error(rw, err.Error(), http.StatusNotFound)
+			return
+		}
+		jsonResponse(rw, map[string]string{"status": "updated", "path": pagePath})
+	})
+
+	mux.HandleFunc("DELETE /api/pages/{path...}", func(rw http.ResponseWriter, r *http.Request) {
+		pagePath := r.PathValue("path")
+		if err := w.DeletePage(r.Context(), pagePath); err != nil {
+			http.Error(rw, err.Error(), http.StatusNotFound)
+			return
+		}
+		jsonResponse(rw, map[string]string{"status": "deleted", "path": pagePath})
+	})
+
+	mux.HandleFunc("GET /api/search", func(rw http.ResponseWriter, r *http.Request) {
+		q := r.URL.Query().Get("q")
+		if q == "" {
+			http.Error(rw, "q parameter is required", http.StatusBadRequest)
+			return
+		}
+		results, err := w.Search(r.Context(), q, 20)
+		if err != nil {
+			http.Error(rw, err.Error(), http.StatusInternalServerError)
+			return
+		}
+		jsonResponse(rw, results)
+	})
+
+	mux.HandleFunc("GET /api/backlinks/{path...}", func(rw http.ResponseWriter, r *http.Request) {
+		pagePath := r.PathValue("path")
+		backlinks, err := w.GetBacklinks(r.Context(), pagePath)
+		if err != nil {
+			http.Error(rw, err.Error(), http.StatusInternalServerError)
+			return
+		}
+		jsonResponse(rw, backlinks)
+	})
 
 	// Settings API endpoints (UI only, not MCP)
 	mux.HandleFunc("GET /api/settings", func(rw http.ResponseWriter, r *http.Request) {
@@ -261,7 +356,7 @@ func runHTTPServer(addr, dir, webuiDir string, idleTimeout time.Duration, stopCh
 	slog.Info("mind-map server starting",
 		slog.String("addr", addr),
 		slog.String("wiki", w.Root()),
-		slog.String("mcp_endpoint", "http://localhost"+addr+"/mcp"),
+		slog.String("url", "http://localhost"+addr),
 	)
 
 	go func() {
@@ -278,6 +373,11 @@ func runHTTPServer(addr, dir, webuiDir string, idleTimeout time.Duration, stopCh
 	return nil
 }
 
+func jsonResponse(rw http.ResponseWriter, v any) {
+	rw.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(rw).Encode(v)
+}
+
 func main() {
 	if err := rootCmd.Execute(); err != nil {
 		fmt.Fprintln(os.Stderr, err)

cmd/mind-map/service.go

@@ -81,7 +81,7 @@ func newServiceConfig(addr, dir, webui string, idleTimeout time.Duration) *servi
 	cfg := &service.Config{
 		Name:        "mind-map",
 		DisplayName: "mind-map",
-		Description: "mind-map wiki server — MCP over HTTP/SSE",
+		Description: "mind-map wiki server",
 		Arguments:   args,
 		Executable:  execPath,
 	}