@opvs-ai/mcp 0.7.4 → 2.6.0

package/README.md

@@ -1,65 +1,178 @@
 # @opvs-ai/mcp
 
-All-in-one MCP server for the **6 public OPVS skills**: AgentBoard, AgentDocs, AgentMemory, OPVS Protocol, Auth, Integrations. ~199 tools total (combined hand-written + generated).
-
-For MCP clients with **per-server tool caps** (Antigravity = 100, some Cursor configs), use the scoped [per-skill packages](https://github.com/martinshein/opvsHUB/tree/main/packages/mcp-skills) instead.
+OPVS MCP server for the **on-demand model** — 10 always-on tools that give any MCP host (Claude Desktop, Cursor, Antigravity, Windsurf, Claude Code) the same surface OPVS-hosted agents see. Everything else is reached through `tool_call` indirection so the package fits under the ~100-tool cap every current MCP client enforces.
+
+| Tool | Wraps | Purpose |
+|------|-------|---------|
+| `tool_search` | registry `/search` | Semantic search by intent (`absent`/`cold`/`warm`/`hot` telemetry signal) |
+| `tool_help` | registry `/packages/{vendor}/{name}` | Methods + manifest on demand |
+| `tool_read` | registry `/packages/{vendor}/{name}/skill-guide` | Read any published skill's actual SKILL.md + `references/` layers on-demand, **nothing installed** (`path` pulls one layer file) |
+| `tool_call` | `/marketplace/runtime/{install_id}/{skill}/{method}` | Universal proxy — `manifest.skills[].id` routing |
+| `tool_pin` | gateway `skill_pin` *(see "tool_pin status")* | Pin/unpin a skill into an OPVS agent's TOOLS.md |
+| `tool_list_installed` | `/marketplace/installed` | What this brand has |
+| `tool_install` | `/marketplace/packages/{id}/install` | Add a package with explicit consent |
+| `tool_uninstall` | `DELETE /marketplace/installed/{id}` | Remove a package |
+| `whoami` | `/auth/me` | Session probe — brand, agent, workspace |
+| `board_as_markdown` | `/board/boards/{id}/export?format=md` | A whole AgentBoard as a Markdown plan in one call (`detail` summary/standard/full, `columns` filter) |
+
+All tool names match `^[a-zA-Z0-9_-]+$` (the OpenAI tool-name regex; dots break Lola/Roni/planner on first call).
 
 ## Install
 
+This package is published to OPVS's Verdaccio registry only (npm.opvs.ai). Configure your client to pull `@opvs-ai` packages from there:
+
 ```bash
+echo "@opvs-ai:registry=https://npm.opvs.ai/" >> ~/.npmrc
 npm install -g @opvs-ai/mcp
 ```
 
 Provides the `opvs-mcp` binary.
 
+> Public npmjs.com publish is deferred until npmjs credentials recover (Martin lost them 2026-05-14). The package functions identically — only the install path differs.
+
 ## Auth
 
-Reads `~/.opvs/config.json`, shared with `@opvs-ai/cli`. If you've run `opvs auth request` already, this MCP works immediately.
+Reads `~/.opvs/config.json` (shared with `@opvs-ai/cli`). If you've already run `opvs auth request`, this MCP works immediately. The brand is pinned server-side from the PAT — `tool_call` will refuse if the PAT isn't brand-scoped.
+
+```bash
+npm install -g @opvs-ai/cli @opvs-ai/mcp
+opvs auth request -w <workspace-slug> -e <admin-email>
+# (approve the email link)
+opvs whoami     # confirm brand pinned
+```
 
 ## MCP client config
 
-### Claude Code
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
   "mcpServers": {
     "opvs": {
-      "command": "opvs-mcp"
+      "command": "opvs-mcp",
+      "env": { "NODE_NO_WARNINGS": "1" }
     }
   }
 }
 ```
 
-### Claude Desktop / Cursor / Windsurf
+Restart Claude Desktop. `tool_search`, `tool_help`, `tool_call`, etc. appear in the tools menu.
 
-Same shape. Restart the client after adding.
+### Cursor
+
+`~/.cursor/mcp.json` or via Settings → Cursor Settings → Features → MCP:
+
+```json
+{
+  "mcpServers": {
+    "opvs": {
+      "command": "opvs-mcp",
+      "env": { "NODE_NO_WARNINGS": "1" }
+    }
+  }
+}
+```
 
 ### Antigravity
 
-Don't use this package — it exceeds the 100-tool cap. Use scoped per-skill MCPs instead:
+Settings → MCP → Add server. `NODE_NO_WARNINGS=1` is required — Antigravity rejects any stderr text before the JSON-RPC handshake (see [antigravity-debrief memory](../../docs/planning/) for the 2026-04-26 incident).
 
 ```json
 {
   "mcpServers": {
-    "opvs-agentboard": { "command": "opvs-mcp-agentboard" },
-    "opvs-agentdocs":  { "command": "opvs-mcp-agentdocs" }
+    "opvs": {
+      "command": "opvs-mcp",
+      "env": { "NODE_NO_WARNINGS": "1" }
+    }
   }
 }
 ```
 
-## When to use this vs scoped
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "opvs": {
+      "command": "opvs-mcp",
+      "env": { "NODE_NO_WARNINGS": "1" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add opvs -- opvs-mcp
+```
+
+## Worked example
+
+```text
+You: Find restaurants near Aarhus and save the top 5 to a board.
+
+Agent → tool_search({ intent: "find restaurants in Aarhus" })
+     ← { items: [{ vendor: "@spideriq", name: "lead-gen-skills", ... }],
+         telemetry_signal: "warm",
+         _guidance: "#audit.ok ranked=1 best=@spideriq/lead-gen-skills #next:tool_call" }
+
+Agent → tool_help({ name: "@spideriq/lead-gen-skills", section: "methods" })
+     ← { methods: { search_maps: { ... }, submit_job: { ... } } }
+
+Agent → tool_call({
+          skill: "@spideriq/lead-gen-skills",
+          method: "submit_job",
+          params: { type: "spiderMaps", payload: { query: "restaurants", location: "Aarhus" } }
+        })
+     ← { job_id: "...", _guidance: "#audit.ok #next:poll getJobStatus every 5s" }
+```
+
+The agent never had to know all of SpiderIQ's 40+ methods upfront — discovery → describe → invoke flowed through 3 always-on tools (discover → describe → invoke).
+
+## Response contract
+
+Every tool returns a single text-content block whose payload is JSON with:
+
+- **Flat sibling `_guidance: string`** — never a wrapper, never an array.
+- **Optional flat sibling `_findings: [...]`** — only when the server emits one (e.g. `audit_level=all`).
+- **`telemetry_signal`** in search results — closed enum: `absent | cold | warm | hot`.
+
+The contract was locked with SpiderIQ on 2026-05-15 PM. See [`docs/planning/Marketplace/architecture/skills-system-reference.md`](../../docs/planning/Marketplace/architecture/skills-system-reference.md#skills-meta) for the gateway-side semantics this MCP mirrors.
+
+## tool_pin status
+
+`tool_pin` is a **stub** in 1.0.0. The W2.1 TOOLS.md persistence layer is live in the gateway's `skills-meta` plugin (`PUT /api/v1/agents/{id}/tools-md` via Management API + X-API-Key), but that surface isn't reachable from a PAT-authenticated MCP client. Calling `tool_pin` returns:
+
+```json
+{
+  "action": "pin",
+  "skill": "@opvs-ai/agentboard",
+  "agent_id": "lola_001",
+  "changed": false,
+  "_guidance": "#audit.warn:not-supported-via-mcp — ..."
+}
+```
+
+Until W2.MCP.PIN ships the PAT-gated passthrough, manage pins via the OPVS dashboard agent profile editor at `/admin/agents/personas`.
+
+## What was deprecated
+
+This package was previously a 209-tool monolithic MCP exposing every public skill's full surface. That model didn't survive contact with MCP clients — every real client (Antigravity, Cursor, Claude Desktop, Windsurf) enforces a ~100-tool cap and the monolithic build was unusable in practice.
+
+The on-demand model (10 always-on + `tool_call` indirection) reaches the same skills without paying the tool-budget cost. 
 
-| Setup | Pick |
-|-------|------|
-| Claude Code / unlimited-tool client | `@opvs-ai/mcp` (this package) — one install, every public skill |
-| Antigravity / 100-tool cap | Scoped `@opvs-ai/mcp-<skill>` packages |
-| Embedded in a custom agent framework | `@opvs-ai/skills-sdk` directly |
+Versions ≤ 0.7.4 are end-of-life. There is no `@opvs-ai/mcp@0.x → 1.0` migration code path — replace the old install with a fresh one.
 
 ## Related packages
 
-- [@opvs-ai/cli](https://github.com/martinshein/opvsHUB/tree/main/packages/cli) — terminal access (no MCP layer)
-- [@opvs-ai/skills-sdk](https://github.com/martinshein/opvsHUB/tree/main/packages/skills-sdk) — embeddable tool definitions for any Node-based agent
-- [@opvs-ai/mcp-agentboard](https://github.com/martinshein/opvsHUB/tree/main/packages/mcp-skills/agentboard), [mcp-agentdocs, mcp-agentmemory, mcp-opvs-protocol, mcp-auth, mcp-integrations](https://github.com/martinshein/opvsHUB/tree/main/packages/mcp-skills) — scoped per-skill MCPs
+- [`@opvs-ai/cli`](../cli) — terminal access (no MCP layer)
+- [`@opvs-ai/skills`](../opvs-skills) — vendor CLI (publish/install/doctor)
+- Gateway plugin `skills-meta` ([source](../../apps/spideragent/packages/shared/src/plugins/skills-meta/index.ts)) — the in-platform counterpart of this package
 
 ## License
 

package/dist/index.d.ts

@@ -1,17 +1,27 @@
 #!/usr/bin/env node
 /**
- * @opvs-ai/mcp — MCP Server for AgentBoard + AgentDocs
+ * @opvs-ai/mcp — MCP server for the OPVS on-demand model
  *
- * Gives Claude Code, Cursor, and Claude Desktop native tool access
- * to OPVS AgentBoard task management and AgentDocs documentation.
+ * Exposes 11 tools — the 8 that mirror the gateway's `skills-meta` plugin (so
+ * external MCP hosts like Claude Desktop, Cursor, Antigravity and Windsurf get
+ * the same surface OPVS-hosted agents see), plus `board_as_markdown` (Topic 1 /
+ * S1.4 — a whole AgentBoard as a Markdown plan in one call; it has no
+ * `tool_call` route because the agentboard skill ships no schema.yaml), plus
+ * `tool_read` (DLRT 3.2 — read any published skill's actual SKILL.md + its
+ * `references/` layers on-demand from the catalog bundle, with nothing
+ * installed), plus `sandbox_chat` (vendor test mode — drive your marketplace
+ * sandbox test agent through the real gateway, per Vendor-Upstream-and-Testing
+ * decision 4: a MODE of this package, not a new one). Every other capability is
+ * reached through `tool_call` indirection so the package fits under the
+ * ~100-tool cap that all current MCP clients enforce.
  *
- * Transport: stdio (JSON-RPC over stdin/stdout)
- * Auth: reads token from ~/.opvs/config.json (shared with @opvs-ai/cli)
+ * Tool names match OpenAI's `^[a-zA-Z0-9_-]+$` (see
+ * `feedback-openai-tool-name-regex` memory). Dots, `@`, and `/` are rejected.
  *
- * Multi-workspace: every tool accepts an optional `workspace` parameter.
- * If omitted, uses OPVS_WORKSPACE env var or the current workspace from config.
+ * Transport: stdio (JSON-RPC). Never write to stdout outside the SDK.
+ * Debug logs go to stderr via console.error().
  *
- * IMPORTANT: Never use console.log() — it corrupts the stdio transport.
- * Use console.error() for debug logging.
+ * Auth: PAT from `~/.opvs/config.json` (shared with `@opvs-ai/cli`). Brand is
+ * pinned server-side from the PAT — never trust LLM-supplied brand_id.
  */
 export {};