mcpengine/infra/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:
```markdown
- **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:
```typescript
return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
```

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

And the tool definition should include:
```typescript
{
  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:
```typescript
// 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:
```typescript
{
  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:
```typescript
{
  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:
```typescript
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:
```bash
# Use MCP Inspector for protocol testing
npx @modelcontextprotocol/inspector stdio node dist/index.js
```

The [MCP Inspector](https://github.com/modelcontextprotocol/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):
```json
{
  "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+):
```json
{
  "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.*