From 77c635b16bcc93470722a2aa528170da043a8424 Mon Sep 17 00:00:00 2001 From: Andrey Oblivantsev Date: Thu, 13 Aug 2026 21:26:06 +0100 Subject: [PATCH] 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. --- AGENTS.md | 1 + PLAN.md | 3 +- README.md | 2 +- bin/brain/serve.go | 3 + bin/tools/test_published_docs.py | 8 ++ docs/design.md | 9 +- internal/httpapi/mcp.go | 185 +++++++++++++++++++++++++++++++ internal/httpapi/server.go | 26 ++++- internal/httpapi/spec.go | 126 +++++++++++++++++++++ internal/httpapi/spec_test.go | 86 ++++++++++++++ skills/brain/SKILL.md | 2 + 11 files changed, 442 insertions(+), 9 deletions(-) create mode 100644 internal/httpapi/mcp.go create mode 100644 internal/httpapi/spec.go create mode 100644 internal/httpapi/spec_test.go diff --git a/AGENTS.md b/AGENTS.md index 7401bae..97ef9c9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,6 +85,7 @@ bin/brain/search.go "query" --no-web # local graph only bin/brain/get.go [--body] [--json] # Go read; Python bin/kb/get CI fallback bin/brain/stats.go [--json] bin/brain/eval.go [--json] # recall@5; questions in internal/brain/rank +bin/brain/serve.go # HTTP :8630; GET /openapi.json POST /mcp bin/markdown/import.go [dir] # mistune leaves → YAML bin/git/import.go [REPO] [--json] [--limit N] # go-git history → commit leafs bin/web/search.go "query" [--json] # SearXNG; throttled ≠ absence diff --git a/PLAN.md b/PLAN.md index ff9a089..9ca2d5c 100644 --- a/PLAN.md +++ b/PLAN.md @@ -43,6 +43,7 @@ detective method: **a fact needs ≥2 independent sources or it is | D17 | assertion gate | Fact-check every *claim* (facts → info → live → web), not every edit. `bin/brain/search.go` adds a `web` block when there is no facts hit (`throttled`/`skipped`/`refused` ≠ absence). `--root` and `--no-web` stay local. Missing graph ≠ “does not exist”. | | D18 | reasoner | Pluggable OpenAI-compatible URL. RAM: Qwen3.5-9B. Quality: Bonsai-27B or Qwen3.6-27B. No official Qwen3.6-9B. | | D19 | git history | [go-git](https://github.com/go-git/go-git) via `bin/git/import.go`. No subprocess of the git binary. Conversion prints commit leafs; brain write is `bin/brain/index.go`. | +| D20 | agent API | OpenAPI + MCP are generated from the same `internal/httpapi.Ops` table as `bin/brain/serve.go` handlers. `GET /openapi.json`, `POST /mcp` (JSON-RPC tools/list + tools/call). Tool names match OpenAPI paths (`search`/`get`/`stats`/`audit`). | ## Architecture @@ -58,7 +59,7 @@ detective method: **a fact needs ≥2 independent sources or it is brain/get.go stats.go eval.go # Go read (cgo); Python bin/kb/* CI fallback brain/watch.go brain/search.go deduction: facts → info → web-search - brain/serve.go HTTP API in-process (internal/httpapi + internal/brain) + brain/serve.go HTTP API in-process + OpenAPI/MCP (D20) mail/import.go JSON → markdown (no brain write) markdown/import.go mistune leaves postgres/query.go read-only YAML (wraps bin/db/psql-yq) diff --git a/README.md b/README.md index c473c75..3e200d2 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ bin/brain/search.go "invoice from last week" # same s `bin/{subject}/{method}.go` — self-describing: shebang on line 1, usage comment from line 2. Shared code in `internal/`. YAML default output, `--json` for machines. Tests gate every commit. HTTP: `bin/brain/serve.go` calls -`internal/brain` in-process (`/health` `/search` `/get` `/stats` `/audit` `/ingest`). +`internal/brain` in-process (`/health` `/search` `/get` `/stats` `/audit` `/ingest` `/openapi.json` `/mcp`). ## Development diff --git a/bin/brain/serve.go b/bin/brain/serve.go index 1f24dac..21e9e30 100755 --- a/bin/brain/serve.go +++ b/bin/brain/serve.go @@ -6,6 +6,9 @@ // KB_ROOT=/path/to/2dph ./bin/brain/serve.go // KB_WORKERS=4 KB_PORT=8630 ./bin/brain/serve.go // +// GET /openapi.json same Ops table as the handlers +// POST /mcp JSON-RPC tools/list + tools/call +// // Needs CGO + libladybug (same as bin/brain/search.go). // NOTE: never run `gofmt -w` on this file — it breaks the shebang. package main diff --git a/bin/tools/test_published_docs.py b/bin/tools/test_published_docs.py index 7af97b8..486fe01 100644 --- a/bin/tools/test_published_docs.py +++ b/bin/tools/test_published_docs.py @@ -67,6 +67,14 @@ class PublishedDocsTest(unittest.TestCase): self.assertIn("internal/brain/rank", design) self.assertIn("They do not exec Python", design) + def test_openapi_mcp_from_same_handlers(self) -> None: + plan = (ROOT / "PLAN.md").read_text() + self.assertIn("D20", plan) + self.assertIn("/openapi.json", (ROOT / "README.md").read_text()) + self.assertIn("/mcp", (ROOT / "README.md").read_text()) + skill = (ROOT / "skills" / "brain" / "SKILL.md").read_text() + self.assertIn("/mcp", skill) + def test_readme_search_escalates_web(self) -> None: text = (ROOT / "README.md").read_text() self.assertIn("--no-web", text) diff --git a/docs/design.md b/docs/design.md index 52002b1..02f1cdb 100644 --- a/docs/design.md +++ b/docs/design.md @@ -69,4 +69,11 @@ Conflicting pairings (≥2 yes vs ≥2 no) = hypothesis (OQ1 → v2 resolution). (`system_ladybug`). They do not exec Python. Control questions for recall@5 live in `internal/brain/rank` so CI can test the table without libladybug. Python `bin/kb/{get,stats,eval}` remain for GitHub Actions until the runner -has ladybug cgo. Index/write is still `bin/kb/index`. \ No newline at end of file +has ladybug cgo. Index/write is still `bin/kb/index`. + +## Agent API (D20) + +`bin/brain/serve.go` exposes the same `internal/httpapi.Ops` table as OpenAPI +(`GET /openapi.json`) and MCP (`POST /mcp` JSON-RPC `tools/list` + +`tools/call`). Tool names match paths: `search`, `get`, `stats`, `audit`. +Agents should use these endpoints instead of shebang CLIs. \ No newline at end of file diff --git a/internal/httpapi/mcp.go b/internal/httpapi/mcp.go new file mode 100644 index 0000000..dbd6d16 --- /dev/null +++ b/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 == "" { + 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 == "" { + 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 +} diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go index 4aaee9b..061dce5 100644 --- a/internal/httpapi/server.go +++ b/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{}{}: diff --git a/internal/httpapi/spec.go b/internal/httpapi/spec.go new file mode 100644 index 0000000..3af32c4 --- /dev/null +++ b/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 +} diff --git a/internal/httpapi/spec_test.go b/internal/httpapi/spec_test.go new file mode 100644 index 0000000..0c27a22 --- /dev/null +++ b/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() +} diff --git a/skills/brain/SKILL.md b/skills/brain/SKILL.md index d71f4f2..98f4668 100644 --- a/skills/brain/SKILL.md +++ b/skills/brain/SKILL.md @@ -44,4 +44,6 @@ are not wired yet); do not treat it as a graph walk. are not evidence of absence. `--root facts|info` and `--no-web` skip the web. - If recall looks wrong, run `bin/brain/eval.go`; it gates control questions and should stay at or above 95% recall@5. +- Agents: `GET /openapi.json` and `POST /mcp` on `bin/brain/serve.go` (same + handlers; tool names match paths `search`/`get`/`stats`/`audit`). - Never report an unconfirmed single-source local answer as fact. \ No newline at end of file