clawdbot-workspace/mcp-factory-reviews/alpha-protocol-review.md

Agent Alpha — MCP Protocol & Standards Review

Date: 2026-02-04 Reviewer: Agent Alpha (MCP Protocol & Standards Expert) Scope: MCP-FACTORY.md + 5 skills (mcp-api-analyzer, mcp-server-builder, mcp-app-designer, mcp-localbosses-integrator, mcp-qa-tester) Spec Versions Reviewed Against: MCP 2025-06-18, MCP 2025-11-25 (current), TS SDK v1.26.0 (current stable), TS SDK v2 (pre-alpha)

---

Executive Summary

1. The skills are built against an outdated SDK surface area. The current @modelcontextprotocol/sdk is at v1.26.0 (not "v1.x+" as vaguely stated), and the v2 SDK (pre-alpha, targeting Q1 2026) splits into @modelcontextprotocol/server + @modelcontextprotocol/client. The skills reference "^1.0.0" in package.json — this will work but isn't pinned strategically.

2. Three major MCP features from the 2025-06-18 and 2025-11-25 specs are completely missing: outputSchema / structuredContent (structured tool outputs), Elicitation (server-requested user input), and Tasks (async long-running operations). These are significant omissions for a Feb 2026 pipeline.

3. Transport coverage is stdio-only. The spec now defines Streamable HTTP as the recommended remote transport, and legacy SSE is deprecated. Our server template only shows StdioServerTransport — this is fine for Claude Desktop but severely limits deployment patterns.

4. Tool metadata is incomplete. The 2025-11-25 spec added title, icons, and outputSchema to the Tool definition. Our skills only cover annotations (readOnlyHint etc.) — we're missing the new first-class fields.

5. The "MCP Apps" pattern is entirely custom (LocalBosses-specific). This is NOT the same as MCP structuredContent. The skills conflate our proprietary APP_DATA block system with MCP protocol features. This should be clearly documented as a LocalBosses extension, not MCP standard.

---

Per-Skill Reviews

1. MCP API Analyzer (mcp-api-analyzer)

Overall Grade: B+ — Solid analysis framework, but missing modern spec awareness.

Issues:

CRITICAL — Missing outputSchema planning: The tool inventory section defines inputSchema annotations but never plans for outputSchema. Since MCP 2025-06-18, tools can declare output schemas for structured content. The analysis template should include a "Response Schema" field per tool that captures the expected output structure. This feeds directly into structuredContent at build time.

Action: Add to Section 6 (Tool Inventory) template:

- **Output Schema:** `{ data: Contact[], meta: { total, page, pageSize } }`

MODERATE — Missing Elicitation candidate identification: The MCP 2025-06-18 spec introduced elicitation — servers can request user input mid-flow. The analyzer should identify endpoints/flows that would benefit from interactive elicitation (e.g., "Which account do you want to connect?" during auth, "Confirm before deleting?" for destructive ops). This is a new category of analysis.

Action: Add Section 7b: "Elicitation Candidates" — flows where the server should request user input.

MODERATE — Tool naming convention mismatch: The skill mandates snake_case (list_contacts), which is fine and valid per spec. But the 2025-11-25 spec now formally documents tool naming guidance that also allows camelCase and dot.notation (e.g., admin.tools.list). The dot notation is useful for namespacing tool groups. Consider documenting dot notation as an alternative for large APIs.

MINOR — Missing title field planning: The 2025-11-25 spec added an optional title field to tools (human-readable display name, separate from the machine-oriented name). The analyzer should capture a human-friendly title for each tool.

MINOR — Content annotations not planned: MCP content (text, images) can now carry audience (["user", "assistant"]) and priority (0.0-1.0) annotations. These should be planned during analysis — some tool outputs are user-facing (show in UI) vs assistant-facing (feed back to LLM).

What's Good:

• Excellent annotation decision tree (GET→readOnly, DELETE→destructive, etc.)
• Strong app candidate selection criteria
• Good tool description formula ("What it does. What it returns. When to use it.")
• Practical pagination pattern documentation

---

2. MCP Server Builder (mcp-server-builder)

Overall Grade: B- — Functional but architecturally dated. Multiple spec gaps.

Issues:

CRITICAL — Missing outputSchema and structuredContent in tool definitions: Since MCP 2025-06-18, tools SHOULD declare an outputSchema and return results via structuredContent alongside the content text fallback. Our template only returns:

return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };

It should return:

return {
  content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
  structuredContent: result,  // The actual typed object
};

And the tool definition should include:

{
  name: "list_contacts",
  title: "List Contacts",  // NEW in 2025-11-25
  description: "...",
  inputSchema: { ... },
  outputSchema: {           // NEW in 2025-06-18
    type: "object",
    properties: {
      data: { type: "array", items: { ... } },
      meta: { type: "object", ... }
    }
  },
  annotations: { ... }
}

This is a fundamental protocol compliance issue. Without structuredContent, clients that expect typed responses will fall back to parsing text — fragile and error-prone.

CRITICAL — Transport is stdio-only: The server template only shows StdioServerTransport. The MCP 2025-11-25 spec defines two standard transports:

1. stdio — for local subprocess spawning (Claude Desktop, Cursor)
2. Streamable HTTP — for remote/production servers (recommended for scalability)

Legacy SSE is deprecated. The builder skill should provide BOTH transport patterns:

// stdio (default for local use)
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Streamable HTTP (for remote deployment)
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

At minimum, the README should document how to add Streamable HTTP for production deployment.

CRITICAL — Missing title field on tools: The 2025-11-25 spec added title as a first-class tool property for human-readable display. Our skills never set it. Every tool should have:

{
  name: "list_contacts",
  title: "List Contacts",  // Human-readable, shown in UIs
  ...
}

MODERATE — Error handling doesn't distinguish Protocol Errors vs Tool Execution Errors: The MCP spec now (clarified in 2025-11-25) formally distinguishes:

• Protocol Errors: JSON-RPC error codes (-32600, -32601, -32602, -32603) for structural issues
• Tool Execution Errors: isError: true in the result for business/API failures

The spec explicitly states that input validation errors should be Tool Execution Errors (not Protocol Errors) to enable LLM self-correction. Our Zod validation errors are correctly returned as Tool Execution Errors (good), but we don't document this distinction or handle it intentionally.

MODERATE — Missing resource_link in tool results: Tools can now return resource_link content items, pointing to MCP Resources for additional context. For API tools that return entities, returning a resource link allows the client to subscribe to updates:

{
  type: "resource_link",
  uri: `service://contacts/${contact.id}`,
  name: contact.name,
  mimeType: "application/json"
}

MODERATE — SDK version pinning is vague: "@modelcontextprotocol/sdk": "^1.0.0" could resolve to v1.0.0 (ancient) or v1.26.0 (current). Should be "^1.25.0" minimum to get 2025-11-25 spec support including tasks, icons, and elicitation fixes.

MODERATE — No mention of Zod v4 compatibility: The SDK v1.x now imports from zod/v4 internally but maintains backwards compatibility with Zod v3.25+. Our template uses zod ^3.22.4 — this should be updated to ^3.25.0 minimum or note the Zod v4 migration path.

MODERATE — No capabilities declaration for features: The server initialization only declares { capabilities: { tools: {} } }. If we plan to use resources, prompts, or logging, these capabilities MUST be declared at init:

const server = new Server(
  { name: `${MCP_NAME}-mcp`, version: MCP_VERSION },
  {
    capabilities: {
      tools: { listChanged: false },
      resources: {},      // if serving resources
      prompts: {},        // if serving prompts
      logging: {},        // for structured logging
    }
  }
);

MINOR — Missing icons on tools: The 2025-11-25 spec allows tools to declare icons for UI display. Low priority but nice for rich clients.

MINOR — Missing JSON Schema 2020-12 awareness: The 2025-11-25 spec establishes JSON Schema 2020-12 as the default dialect. Our Zod-to-JSON-Schema conversion should be validated against this.

What's Good:

• Clean modular architecture with lazy loading
• Solid API client pattern with retry/rate-limit logic
• Good Zod validation patterns
• Quality gate checklist is comprehensive

---

3. MCP App Designer (mcp-app-designer)

Overall Grade: B — Well-crafted UI system, but conceptually disconnected from MCP protocol.

Issues:

CRITICAL — Conflation of LocalBosses apps with MCP protocol: The entire app system (postMessage, polling, APP_DATA blocks) is a proprietary LocalBosses pattern, NOT an MCP protocol feature. The skill should be explicit about this:

• MCP's structuredContent is the protocol-level structured output
• LocalBosses' APP_DATA rendering is a client-side UI layer that CONSUMES MCP structured content
• These are different layers and should not be confused

The skill should document how structuredContent from MCP tools feeds into the app rendering pipeline.

MODERATE — No integration with MCP structuredContent: The app template receives data via postMessage with type mcp_app_data. But the actual data source should be MCP tool results with structuredContent. The architecture section should show how LocalBosses parses structuredContent from tool results and routes it to the appropriate app via postMessage.

MODERATE — Missing Resource subscription pattern: MCP Resources support subscriptions (clients can subscribe to resource changes and get notifications). Apps could subscribe to resources for real-time updates instead of polling. This is a more MCP-native pattern than the 3-second polling interval.

MINOR — App template doesn't handle resource_link content: If MCP tools return resource_link items, the app system should be able to follow those links to fetch additional data.

What's Good:

• Excellent dark theme design system with clear tokens
• 8 app type templates are comprehensive and well-designed
• Three-state rendering (loading/empty/data) is solid
• Responsive design requirements are practical
• Self-contained HTML pattern is pragmatic

---

4. MCP LocalBosses Integrator (mcp-localbosses-integrator)

Overall Grade: B — Solid integration guide, but the system prompt approach bypasses MCP's native features.

Issues:

CRITICAL — APP_DATA block format bypasses MCP protocol: The <!--APP_DATA:{...}:END_APP_DATA--> pattern works, but it's embedding structured data in LLM-generated text, which is fragile. The proper MCP approach would be:

1. LLM calls an MCP tool
2. Tool returns structuredContent with typed data
3. Client (LocalBosses) receives typed data natively
4. Client routes data to the appropriate app

Instead, we're asking the LLM to generate JSON inside HTML comments, which is:

• Error-prone (LLMs can produce invalid JSON)
• Not validated against any schema
• Not leveraging MCP's outputSchema validation
• Duplicating data (once in text for the user, once in the APP_DATA block)

MODERATE — System prompt engineering could leverage MCP Prompts: MCP has a first-class prompts capability. The system prompts for each channel could be registered as MCP Prompt resources, making them discoverable and versionable through the protocol rather than hardcoded in route.ts.

MODERATE — No mention of MCP Roots: MCP Roots let clients inform servers about workspace/project scope. For a multi-channel system like LocalBosses, roots could be used to scope which service's data is relevant in each channel.

MINOR — Intake questions could use MCP Elicitation: The app intake system (asking users questions before showing data) maps directly to MCP's elicitation capability. Instead of a custom intake system, the server could use elicitation/create to request initial parameters from the user.

What's Good:

• Clear file-by-file integration guide
• Cross-reference verification checklist is essential
• Complete example (Calendly) is helpful
• System prompt engineering guidelines are practical

---

5. MCP QA Tester (mcp-qa-tester)

Overall Grade: B+ — Thorough testing framework, but missing protocol-level validation.

Issues:

CRITICAL — No MCP protocol compliance testing: The testing layers cover static analysis, visual testing, functional testing, and API testing — but never test MCP protocol compliance itself. Missing tests:

• Does the server respond correctly to tools/list?
• Does every tool return valid structuredContent matching its outputSchema?
• Does the server handle initialize → initialized lifecycle correctly?
• Are notifications/tools/list_changed sent when appropriate?
• Do error responses use correct JSON-RPC error codes?

Action: Add "Layer 0: MCP Protocol Compliance" testing:

# Use MCP Inspector for protocol testing
npx @modelcontextprotocol/inspector stdio node dist/index.js

The MCP Inspector is the official tool for this — it should be the first thing we run.

MODERATE — No structuredContent validation: If tools declare outputSchema, the spec says "Servers MUST provide structured results that conform to this schema." QA should validate every tool's actual output against its declared schema.

MODERATE — Missing transport testing: QA only tests the app/UI layer. It should also test:

• stdio transport: Can the server be launched as a subprocess and respond to JSON-RPC?
• (If Streamable HTTP added): Can the server handle HTTP POST/GET, session management, SSE streams?

MINOR — No sampling/elicitation testing: If servers implement sampling or elicitation, these need test scenarios.

MINOR — Automated script is bash-only: The QA script could leverage the MCP Inspector CLI for automated protocol testing rather than just checking file existence.

What's Good:

• 5-layer testing model is comprehensive
• Visual testing with Peekaboo/Gemini is creative
• Thread lifecycle testing is thorough
• Common issues & fixes table is practical
• Test report template is well-structured

---

Research Findings: What's New/Changed

MCP Spec Versions (timeline):

Version	Date	Key Features
2024-11-05	Nov 2024	Initial spec (tools, resources, prompts, sampling)
2025-03-26	Mar 2025	Streamable HTTP transport, annotations (readOnlyHint etc.)
2025-06-18	Jun 2025	structuredContent, outputSchema, Elicitation, OAuth 2.0, resource_link
2025-11-25	Nov 2025	Tasks (async), icons, title field, URL elicitation, tool naming guidance, incremental OAuth scope

TypeScript SDK Status (Feb 2026):

• v1.26.0 (released Feb 4, 2026) — current stable, implements 2025-11-25 spec
• v2 pre-alpha (targeting Q1 2026 stable) — BREAKING: splits into @modelcontextprotocol/server + @modelcontextprotocol/client, uses Zod v4, adds middleware packages (Express, Hono, Node HTTP)
• v1.x will receive bug fixes for 6+ months after v2 ships

Features We're Completely Ignoring:

1. structuredContent + outputSchema (2025-06-18)

   • Tools can declare typed output schemas
   • Results include both content (text fallback) and structuredContent (typed JSON)
   • Clients validate structured output against the schema
   • Impact: HIGH — This is the proper way to send typed data to our apps

2. Elicitation (2025-06-18, enhanced 2025-11-25)

   • Form mode: Server requests structured user input via JSON Schema forms
   • URL mode: Server directs user to external URL for sensitive operations (OAuth, payments)
   • Impact: HIGH — Replaces our custom intake system, enables mid-tool user interaction

3. Tasks (2025-11-25, experimental)

   • Long-running tool calls become tasks that can be polled/resumed
   • Enables "call now, fetch later" pattern
   • Impact: MODERATE — Useful for slow API calls, batch operations

4. Tool title + icons (2025-11-25)

   • Human-readable display name separate from machine name
   • Icon arrays for UI rendering
   • Impact: LOW — Nice for rich clients

5. Content annotations (audience, priority)

   • Content blocks can specify intended audience (user vs assistant)
   • Priority hints for UI rendering order
   • Impact: LOW — Useful for controlling what the user sees vs what feeds back to LLM

6. Streamable HTTP transport (2025-03-26)

   • HTTP POST/GET with optional SSE streaming
   • Session management via MCP-Session-Id header
   • Resumability via Last-Event-ID
   • Impact: MODERATE — Needed for remote/production deployment, not just local stdio

7. MCP Resources as tool output (resource_link)

   • Tools can return links to subscribable resources
   • Impact: LOW for now, but enables real-time data patterns

8. MCP Registry (GA targeting soon)

   • Central index of MCP servers
   • Server identity via .well-known URLs
   • Impact: LOW for our internal use, but relevant if publishing servers

---

Priority Recommendations (Ranked by Impact)

P0 — Must Fix (blocks Feb 2026 compliance)

1. Add structuredContent + outputSchema to server builder

• Every tool should declare an outputSchema
• Every tool result should include both content and structuredContent
• This is THE most impactful change — it's the standard way to return typed data
• Directly benefits the app system (structured data replaces text parsing)

2. Add title field to all tool definitions

• Simple change, required by modern clients (VS Code, Claude Desktop)
• title: "List Contacts" alongside name: "list_contacts"

3. Pin SDK version to ^1.25.0 minimum

• Ensures 2025-11-25 spec support
• Update Zod peer dep to ^3.25.0

P1 — Should Fix (significant quality improvement)

4. Add Streamable HTTP transport option to server builder

• Provide both stdio and HTTP transport patterns
• README should document remote deployment
• Doesn't need to replace stdio, just offer it as an option

5. Add Elicitation to the server builder template

• Document how tools can request user input via elicitation/create
• Map to our existing intake system
• Especially useful for destructive operations ("Are you sure?")

6. Add MCP protocol compliance testing to QA skill

• Integrate MCP Inspector as Layer 0
• Test tools/list, tools/call, lifecycle, error codes
• Validate structuredContent against outputSchema

7. Clarify LocalBosses app pattern vs MCP protocol

• APP_DATA is LocalBosses-specific, not MCP
• Document the bridge: MCP structuredContent → LocalBosses app rendering
• Long-term: replace APP_DATA HTML comments with proper tool result routing

P2 — Nice to Have (forward-looking)

8. Add Tasks (async) support for slow API operations

• Experimental in 2025-11-25, but useful for batch operations
• Mark as experimental in the template

9. Add content annotations (audience, priority) to tool results

• Route user-facing content to apps, assistant-facing content to LLM context
• Low effort, moderate polish improvement

10. Plan for SDK v2 migration

• v2 targets Q1 2026 stable release
• Package split: @modelcontextprotocol/server + @modelcontextprotocol/client
• Zod v4 is the default
• Middleware packages for Express/Hono/Node HTTP
• Add a migration note to the builder skill

11. Add outputSchema planning to the API analyzer

• For each tool, capture the expected response schema
• This feeds directly into the builder's outputSchema declarations

12. Add Elicitation candidates to the API analyzer

• Identify flows that benefit from mid-tool user interaction
• Auth confirmation, destructive operation confirmation, multi-step wizards

---

Appendix: Quick Reference — What the Spec Says Now

Tool Definition (2025-11-25):

{
  "name": "list_contacts",
  "title": "Contact List",
  "description": "List contacts with filters...",
  "icons": [{ "src": "...", "mimeType": "image/png" }],
  "inputSchema": { "type": "object", ... },
  "outputSchema": { "type": "object", ... },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  }
}

Tool Result with structuredContent (2025-06-18+):

{
  "content": [
    { "type": "text", "text": "{\"data\":[...]}" }
  ],
  "structuredContent": {
    "data": [{ "name": "John", "email": "john@example.com" }],
    "meta": { "total": 150, "page": 1 }
  },
  "isError": false
}

Error Handling (2025-11-25):

• Protocol Errors: JSON-RPC error codes (-32600 to -32603, -32700)
  • Unknown tool, malformed request, server errors
• Tool Execution Errors: isError: true in result
  • API failures, validation errors, business logic errors
  • Input validation errors SHOULD be Tool Execution Errors (enables LLM self-correction)

Transports:

1. stdio — local subprocess, recommended for desktop clients
2. Streamable HTTP — HTTP POST/GET with optional SSE, recommended for production
3. SSE (legacy) — deprecated, use Streamable HTTP instead

---

Review complete. The pipeline is solid as a production framework — but it was designed around the 2025-03-26 spec and needs updating for the 2025-06-18 and 2025-11-25 spec releases. The three biggest gaps are structuredContent/outputSchema, the title field, and transport diversity. Fix those and this pipeline is genuinely state-of-the-art.