feat: OpenAPI and MCP from the same serve handlers (#20)

Agents get GET /openapi.json and POST /mcp. Tool names match
search/get/stats/audit paths so PicoClaw does not need shebangs.

internal/httpapi/mcp.go

@@ -0,0 +1,185 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+)
+
+type rpcReq struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params"`
+}
+
+type rpcErr struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+}
+
+func (s *Server) handleOpenAPI(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, OpenAPI())
+}
+
+func (s *Server) handleMCP(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeJSON(w, http.StatusMethodNotAllowed, map[string]any{"error": "POST JSON-RPC"})
+		return
+	}
+	raw, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]any{"error": "read body"})
+		return
+	}
+	var req rpcReq
+	if err := json.Unmarshal(raw, &req); err != nil {
+		writeJSON(w, http.StatusOK, rpcResult(nil, nil, &rpcErr{-32700, "parse error"}))
+		return
+	}
+	result, rpcErrv, callErr := s.mcpDispatch(r, req)
+	if callErr != nil {
+		writeJSON(w, http.StatusOK, rpcResult(req.ID, nil, &rpcErr{-32603, callErr.Error()}))
+		return
+	}
+	writeJSON(w, http.StatusOK, rpcResult(req.ID, result, rpcErrv))
+}
+
+func (s *Server) mcpDispatch(r *http.Request, req rpcReq) (any, *rpcErr, error) {
+	switch req.Method {
+	case "initialize":
+		return map[string]any{
+			"protocolVersion": "2024-11-05",
+			"capabilities":    map[string]any{"tools": map[string]any{}},
+			"serverInfo":      map[string]any{"name": "2dph", "version": "1"},
+		}, nil, nil
+	case "notifications/initialized", "notifications/cancelled":
+		return map[string]any{}, nil, nil
+	case "tools/list":
+		return map[string]any{"tools": MCPTools()}, nil, nil
+	case "tools/call":
+		out, err := s.mcpCall(r, req.Params)
+		return out, nil, err
+	case "ping":
+		return map[string]any{}, nil, nil
+	default:
+		return nil, &rpcErr{-32601, "method not found"}, nil
+	}
+}
+
+func (s *Server) mcpCall(r *http.Request, params json.RawMessage) (any, error) {
+	var p struct {
+		Name      string         `json:"name"`
+		Arguments map[string]any `json:"arguments"`
+	}
+	if err := json.Unmarshal(params, &p); err != nil {
+		return nil, fmt.Errorf("params")
+	}
+	if p.Arguments == nil {
+		p.Arguments = map[string]any{}
+	}
+	var (
+		body []byte
+		err  error
+	)
+	switch p.Name {
+	case "search":
+		q := strings.TrimSpace(fmt.Sprint(p.Arguments["q"]))
+		if q == "" || q == "<nil>" {
+			return mcpText(`{"error":"q required"}`, true), nil
+		}
+		limit := 10
+		if raw, ok := p.Arguments["n"]; ok {
+			switch n := raw.(type) {
+			case float64:
+				limit = int(n)
+			case string:
+				if v, e := strconv.Atoi(n); e == nil {
+					limit = v
+				}
+			}
+		}
+		if limit < 1 || limit > 100 {
+			return mcpText(`{"error":"n must be int 1..100"}`, true), nil
+		}
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Search(r.Context(), q, limit)
+	case "get":
+		id := strings.TrimSpace(fmt.Sprint(p.Arguments["id"]))
+		if id == "" || id == "<nil>" {
+			return mcpText(`{"error":"id required"}`, true), nil
+		}
+		full := false
+		switch v := p.Arguments["body"].(type) {
+		case bool:
+			full = v
+		case string:
+			full = v == "1" || v == "true"
+		}
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Get(r.Context(), id, full)
+	case "stats":
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Stats(r.Context())
+	case "audit":
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Audit(r.Context())
+	case "ingest":
+		if !s.tryAcquire(r) {
+			return nil, fmt.Errorf("cancelled")
+		}
+		defer s.release()
+		body, err = s.api.Ingest(r.Context())
+	default:
+		return nil, fmt.Errorf("unknown tool %s", p.Name)
+	}
+	if err != nil {
+		return mcpText(err.Error(), true), nil
+	}
+	return mcpText(string(body), false), nil
+}
+
+func mcpText(text string, isError bool) map[string]any {
+	return map[string]any{
+		"content": []any{map[string]any{"type": "text", "text": text}},
+		"isError": isError,
+	}
+}
+
+type rpcResp struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id"`
+	Result  any             `json:"result,omitempty"`
+	Error   *rpcErr         `json:"error,omitempty"`
+}
+
+func rpcResult(id json.RawMessage, result any, err *rpcErr) rpcResp {
+	out := rpcResp{JSONRPC: "2.0", ID: id}
+	if len(id) == 0 {
+		out.ID = []byte("null")
+	}
+	if err != nil {
+		out.Error = err
+		return out
+	}
+	if result == nil {
+		result = map[string]any{}
+	}
+	out.Result = result
+	return out
+}

internal/httpapi/server.go

@@ -48,18 +48,22 @@ func NewServer(api API, workers int) http.Handler {
 
 func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	switch r.URL.Path {
-	case "/health":
+	case PathHealth:
 		writeJSON(w, http.StatusOK, map[string]any{"status": "ok"})
-	case "/search":
+	case PathSearch:
 		s.handleSearch(w, r)
-	case "/get":
+	case PathGet:
 		s.handleGet(w, r)
-	case "/stats":
+	case PathStats:
 		s.handleJSON(w, r, s.api.Stats)
-	case "/audit":
+	case PathAudit:
 		s.handleJSON(w, r, s.api.Audit)
-	case "/ingest":
+	case PathIngest:
 		s.handleJSON(w, r, s.api.Ingest)
+	case PathOpenAPI:
+		s.handleOpenAPI(w, r)
+	case PathMCP:
+		s.handleMCP(w, r)
 	default:
 		writeJSON(w, http.StatusNotFound, map[string]any{"error": "not found"})
 	}
@@ -112,6 +116,16 @@ func (s *Server) handleJSON(w http.ResponseWriter, r *http.Request, fn func(cont
 	writeAPI(w, body, err)
 }
 
+func (s *Server) tryAcquire(r *http.Request) bool {
+	return s.acquire(nopWriter{}, r)
+}
+
+type nopWriter struct{}
+
+func (nopWriter) Header() http.Header       { return http.Header{} }
+func (nopWriter) Write([]byte) (int, error) { return 0, nil }
+func (nopWriter) WriteHeader(int)           {}
+
 func (s *Server) acquire(w http.ResponseWriter, r *http.Request) bool {
 	select {
 	case s.semaphore <- struct{}{}:

internal/httpapi/spec.go

@@ -0,0 +1,126 @@
+package httpapi
+
+// Shared HTTP surface: OpenAPI paths and MCP tools are generated from Ops.
+// ServeHTTP must keep the same path strings.
+
+type Param struct {
+	Name, In, Type, Description string
+	Required                    bool
+}
+
+type Op struct {
+	Path, Method, ID, Summary string
+	Params                    []Param
+	MCP                       bool
+}
+
+const (
+	PathHealth  = "/health"
+	PathSearch  = "/search"
+	PathGet     = "/get"
+	PathStats   = "/stats"
+	PathAudit   = "/audit"
+	PathIngest  = "/ingest"
+	PathOpenAPI = "/openapi.json"
+	PathMCP     = "/mcp"
+)
+
+var Ops = []Op{
+	{Path: PathHealth, Method: "get", ID: "health", Summary: "liveness"},
+	{
+		Path: PathSearch, Method: "get", ID: "search", Summary: "deduction search (facts → info → web)",
+		MCP: true,
+		Params: []Param{
+			{Name: "q", In: "query", Type: "string", Description: "search query", Required: true},
+			{Name: "n", In: "query", Type: "integer", Description: "hit limit 1..100 (default 10)"},
+		},
+	},
+	{
+		Path: PathGet, Method: "get", ID: "get", Summary: "read one leaf by id",
+		MCP: true,
+		Params: []Param{
+			{Name: "id", In: "query", Type: "string", Description: "leaf id", Required: true},
+			{Name: "body", In: "query", Type: "boolean", Description: "include full text"},
+		},
+	},
+	{Path: PathStats, Method: "get", ID: "stats", Summary: "index health", MCP: true},
+	{Path: PathAudit, Method: "get", ID: "audit", Summary: "facts confidence histogram", MCP: true},
+	{Path: PathIngest, Method: "get", ID: "ingest", Summary: "rebuild hint (write is v2)", MCP: true},
+	{Path: PathOpenAPI, Method: "get", ID: "openapi", Summary: "OpenAPI 3 document for this server"},
+}
+
+func OpenAPI() map[string]any {
+	paths := map[string]any{}
+	for _, op := range Ops {
+		params := make([]any, 0, len(op.Params))
+		for _, p := range op.Params {
+			params = append(params, map[string]any{
+				"name":        p.Name,
+				"in":          p.In,
+				"required":    p.Required,
+				"description": p.Description,
+				"schema":      map[string]any{"type": p.Type},
+			})
+		}
+		item := map[string]any{
+			"operationId": op.ID,
+			"summary":     op.Summary,
+			"responses": map[string]any{
+				"200": map[string]any{
+					"description": "JSON",
+					"content": map[string]any{
+						"application/json": map[string]any{
+							"schema": map[string]any{"type": "object"},
+						},
+					},
+				},
+			},
+		}
+		if len(params) > 0 {
+			item["parameters"] = params
+		}
+		paths[op.Path] = map[string]any{op.Method: item}
+	}
+	return map[string]any{
+		"openapi": "3.0.3",
+		"info": map[string]any{
+			"title":       "2dph brain",
+			"version":     "1",
+			"description": "Same handlers as bin/brain/serve.go. MCP tools at POST /mcp match these paths.",
+		},
+		"paths": paths,
+	}
+}
+
+type MCPTool struct {
+	Name        string         `json:"name"`
+	Description string         `json:"description"`
+	InputSchema map[string]any `json:"inputSchema"`
+}
+
+func MCPTools() []MCPTool {
+	out := make([]MCPTool, 0, len(Ops))
+	for _, op := range Ops {
+		if !op.MCP {
+			continue
+		}
+		props := map[string]any{}
+		var required []string
+		for _, p := range op.Params {
+			props[p.Name] = map[string]any{"type": p.Type, "description": p.Description}
+			if p.Required {
+				required = append(required, p.Name)
+			}
+		}
+		schema := map[string]any{"type": "object", "properties": props}
+		if len(required) > 0 {
+			schema["required"] = required
+		}
+		out = append(out, MCPTool{
+			Name:        op.ID,
+			Description: op.Summary,
+			InputSchema: schema,
+		})
+	}
+	return out
+}

internal/httpapi/spec_test.go

@@ -0,0 +1,86 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestOpenAPIIncludesCorePaths(t *testing.T) {
+	doc := OpenAPI()
+	raw, err := json.Marshal(doc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	paths, _ := doc["paths"].(map[string]any)
+	for _, p := range []string{"/search", "/get", "/stats", "/audit"} {
+		if _, ok := paths[p]; !ok {
+			t.Fatalf("openapi missing path %s (%s)", p, raw)
+		}
+	}
+}
+
+func TestMCPToolsMatchOpenAPIPaths(t *testing.T) {
+	paths, _ := OpenAPI()["paths"].(map[string]any)
+	tools := MCPTools()
+	if len(tools) == 0 {
+		t.Fatal("no MCP tools")
+	}
+	names := map[string]bool{}
+	for _, tool := range tools {
+		names[tool.Name] = true
+		path := "/" + tool.Name
+		if _, ok := paths[path]; !ok {
+			t.Fatalf("MCP tool %s has no OpenAPI path %s", tool.Name, path)
+		}
+	}
+	for _, need := range []string{"search", "get", "stats", "audit"} {
+		if !names[need] {
+			t.Fatalf("MCP tools missing %s: %v", need, names)
+		}
+	}
+}
+
+func TestOpenAPIHTTP(t *testing.T) {
+	h := NewServer(&fakeSearcher{}, 1)
+	code, body := get(t, h, "/openapi.json")
+	if code != http.StatusOK {
+		t.Fatalf("code = %d body=%s", code, body)
+	}
+	var doc map[string]any
+	if err := json.Unmarshal(body, &doc); err != nil {
+		t.Fatalf("not json: %v", err)
+	}
+	if doc["openapi"] == nil {
+		t.Fatalf("missing openapi version: %s", body)
+	}
+}
+
+func TestMCPToolsListAndCall(t *testing.T) {
+	h := NewServer(&fakeSearcher{}, 1)
+	code, body := postJSON(t, h, "/mcp", `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`)
+	if code != http.StatusOK {
+		t.Fatalf("list code = %d body=%s", code, body)
+	}
+	if !strings.Contains(string(body), `"search"`) {
+		t.Fatalf("tools/list missing search: %s", body)
+	}
+	code, body = postJSON(t, h, "/mcp", `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search","arguments":{"q":"matrix","n":3}}}`)
+	if code != http.StatusOK {
+		t.Fatalf("call code = %d body=%s", code, body)
+	}
+	if !strings.Contains(string(body), "matrix") {
+		t.Fatalf("search call body %s", body)
+	}
+}
+
+func postJSON(t *testing.T, h http.Handler, path, raw string) (int, []byte) {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, path, strings.NewReader(raw))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	return rec.Code, rec.Body.Bytes()
+}