Merge pull request #232 from PaulJPhilp/codex/pr-4-mcp-tool-surface-contract

PR-4: MCP tool-surface contract fix (P1)

Author: PaulJPhilp

packages/mcp-server/README-END-USER.md

@@ -1,13 +1,14 @@
 # Effect Patterns MCP Server — End User Guide
 
-Use the **Effect Patterns MCP server** from your IDE (Cursor, Claude Code, Windsurf, or any MCP client) to search 700+ Effect-TS patterns and browse the rule catalog. The MCP server is a **patterns + rule catalog** tool only; it does not analyze, review, or refactor your code.
+Use the **Effect Patterns MCP server** from your IDE (Cursor, Claude Code, Windsurf, or any MCP client) to search 700+ Effect-TS patterns, browse curated skills, and inspect the rule catalog. The MCP server is a **patterns + skills + rule catalog** tool only; it does not analyze, review, or refactor your code.
 
 ---
 
 ## What You Get
 
 - **Pattern search** — Find patterns by keyword, category, or difficulty (beginner / intermediate / advanced).
 - **Pattern details** — Full docs and code examples for any pattern by ID.
+- **Skills catalog** — Search and retrieve curated Effect-TS skills by query/category.
 - **Rule catalog** (read-only) — List all analysis rule metadata (IDs, severity, categories). No code scanning.
 
 Code analysis, review, refactoring, and pattern code generation are **not** available via MCP; they are offered through the [HTTP API](#http-api) and paid CLI only.
@@ -129,7 +130,7 @@ Never commit API keys; use environment variables or your IDE's secret storage.
 
 ## MCP Tools (Free Tier)
 
-The MCP server exposes **exactly three tools** in production and staging. No other tools (including code analysis or review) are available via MCP.
+The MCP server exposes **exactly five tools** in production and staging. No other tools (including code analysis or review) are available via MCP.
 
 ### 1. `search_patterns`
 
@@ -181,6 +182,38 @@ No parameters.
 
 ---
 
+### 4. `list_skills`
+
+Search skills by query and optional category filters.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `q` | string | No | Search query for skill title/content. |
+| `category` | string | No | Optional skills category filter. |
+| `limit` | number | No | Max results to return. |
+
+**Example prompts:**
+
+- "List skills for Effect testing."
+- "Find skills for service architecture."
+
+---
+
+### 5. `get_skill`
+
+Get full details for a specific skill by slug, including full guidance content.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `slug` | string | Yes | Skill slug identifier. |
+
+**Example prompts:**
+
+- "Get the skill for effect-service."
+- "Show skill details for a testing workflow."
+
+---
+
 ## HTTP API
 
 When you use the **hosted** server, the MCP server forwards tool calls to the HTTP API for patterns and rules only. You can also call the API directly (e.g. from scripts or CI) with the same API key. **MCP tools do not call paid endpoints** — analysis, review, refactoring, and generation are available only when using the HTTP API or paid CLI directly.
@@ -217,7 +250,7 @@ Full request/response shapes: see [MCP Server API Reference](../../docs/mcp-serv
 
 ## Service Tiers
 
-- **MCP (free):** Patterns and rule catalog only — `search_patterns`, `get_pattern`, `list_analysis_rules`. Rate limits apply (e.g. 100 requests per 15 minutes per key). MCP cannot call paid endpoints.
+- **MCP (free):** Patterns, skills, and rule catalog — `search_patterns`, `get_pattern`, `list_analysis_rules`, `list_skills`, `get_skill`. Rate limits apply (e.g. 100 requests per 15 minutes per key). MCP cannot call paid endpoints.
 - **Paid (HTTP API / CLI only):** Code analysis, code review, consistency analysis, apply refactoring, generate pattern code, and higher limits. Use the HTTP API or paid CLI; these capabilities are not available via MCP.
 
 ---

packages/mcp-server/src/tools/tool-implementations.ts

@@ -34,6 +34,18 @@ export type {
 
 import type { CallApiFn, CallToolResult, LogFn, ToolContext } from "@/tools/tool-types.js";
 
+/**
+ * Official MCP tool surface contract for production/staging.
+ * Debug/local may add `get_mcp_config`.
+ */
+export const OFFICIAL_MCP_TOOL_NAMES = [
+  "search_patterns",
+  "get_pattern",
+  "list_analysis_rules",
+  "list_skills",
+  "get_skill",
+] as const;
+
 /**
  * Registers all Effect Patterns tools with the MCP server.
  * Shared implementation for both Stdio and HTTP transports.

packages/mcp-server/tests/mcp-protocol/client-stdio.test.ts

@@ -28,9 +28,15 @@ describe("MCP Client Stdio Connection", () => {
     expect(client.isReady()).toBe(true);
   });
 
-  const PRODUCTION_TOOLS = ["get_pattern", "list_analysis_rules", "search_patterns"] as const;
-
-  it("should expose exactly 3 tools in default/production env (no get_mcp_config)", async () => {
+  const PRODUCTION_TOOLS = [
+    "get_pattern",
+    "get_skill",
+    "list_analysis_rules",
+    "list_skills",
+    "search_patterns",
+  ] as const;
+
+  it("should expose exactly 5 tools in default/production env (no get_mcp_config)", async () => {
     client = await createMCPTestClient({
       apiKey: "test-api-key",
       apiUrl: "http://localhost:3000",
@@ -40,7 +46,7 @@ describe("MCP Client Stdio Connection", () => {
 
     const tools = await client.listTools();
 
-    expect(tools).toHaveLength(3);
+    expect(tools).toHaveLength(5);
     expect([...tools].sort()).toEqual([...PRODUCTION_TOOLS].sort());
     expect(tools).not.toContain("get_mcp_config");
   });
@@ -50,7 +56,13 @@ describe("MCP Client Stdio Connection", () => {
 
     const tools = await client.listTools();
 
-    const allowed = ["search_patterns", "get_pattern", "list_analysis_rules"];
+    const allowed = [
+      "search_patterns",
+      "get_pattern",
+      "list_analysis_rules",
+      "list_skills",
+      "get_skill",
+    ];
     const forbidden = [
       "analyze_code",
       "review_code",
@@ -70,8 +82,8 @@ describe("MCP Client Stdio Connection", () => {
     for (const name of tools) {
       expect(allowedOptional.has(name)).toBe(true);
     }
-    expect(tools.length).toBeGreaterThanOrEqual(3);
-    expect(tools.length).toBeLessThanOrEqual(4);
+    expect(tools.length).toBeGreaterThanOrEqual(5);
+    expect(tools.length).toBeLessThanOrEqual(6);
   });
 
   it("should disconnect gracefully", async () => {

packages/mcp-server/tests/mcp-protocol/local.test.ts

@@ -82,9 +82,15 @@ describe("Local MCP Server", () => {
       expect(client.isReady()).toBe(true);
     });
 
-    const PRODUCTION_TOOLS = ["get_pattern", "list_analysis_rules", "search_patterns"] as const;
-
-    it("should expose exactly 3 tools when MCP_DEBUG=false and MCP_ENV=production", async () => {
+    const PRODUCTION_TOOLS = [
+      "get_pattern",
+      "get_skill",
+      "list_analysis_rules",
+      "list_skills",
+      "search_patterns",
+    ] as const;
+
+    it("should expose exactly 5 tools when MCP_DEBUG=false and MCP_ENV=production", async () => {
       if (!isLocalAvailable) return;
       const productionClient = await createMCPTestClient({
         apiKey: config.apiKey,
@@ -95,7 +101,7 @@ describe("Local MCP Server", () => {
 
       const tools = await productionClient.listTools();
 
-      expect(tools).toHaveLength(3);
+      expect(tools).toHaveLength(5);
       expect([...tools].sort()).toEqual([...PRODUCTION_TOOLS].sort());
       expect(tools).not.toContain("get_mcp_config");
       await productionClient.close();
@@ -105,7 +111,13 @@ describe("Local MCP Server", () => {
       if (!isLocalAvailable) return;
       const tools = await client.listTools();
 
-      const allowed = ["search_patterns", "get_pattern", "list_analysis_rules"];
+      const allowed = [
+        "search_patterns",
+        "get_pattern",
+        "list_analysis_rules",
+        "list_skills",
+        "get_skill",
+      ];
       const forbidden = [
         "analyze_code",
         "review_code",
@@ -125,8 +137,8 @@ describe("Local MCP Server", () => {
       for (const name of tools) {
         expect(allowedOptional.has(name)).toBe(true);
       }
-      expect(tools.length).toBeGreaterThanOrEqual(3);
-      expect(tools.length).toBeLessThanOrEqual(4);
+      expect(tools.length).toBeGreaterThanOrEqual(5);
+      expect(tools.length).toBeLessThanOrEqual(6);
     });
   });