mcp-framework

As of the audit on 2026-04-01, mcp-framework (v0.2.19) is targeting an older version of the Model Context Protocol (MCP) specification (approximately the 2025-03-26 era).

Key Limitations to Note:

• Missing Spec Features: The framework lacks support for several features introduced in the June and November 2025 spec revisions, including tool annotations, structured content, elicitation, tasks, logging protocol, progress tracking, and audio content.
• SDK Version: The framework uses @modelcontextprotocol/sdk@1.11.0, which is significantly behind the latest version (1.29.0).
• Protocol Gaps: It does not yet support the MCP-Protocol-Version HTTP header or the Implementation.description field required by newer Streamable HTTP specifications.

Use this framework if you need a stable implementation of core primitives like tools, prompts, resources, sampling, and completions, but be aware that advanced protocol features and the latest spec enhancements are not yet available.

The mcp-framework is undergoing a multi-phase implementation plan to align with the MCP 2025-11-25 specification. The roadmap follows a strict dependency graph where foundational SDK upgrades and security hardening must occur before schema evolution and advanced features like audio content or task management are implemented.

Execution Order

1. Phase 0: SDK Upgrade (Foundation)
2. Phase 1: Security Hardening (Origin validation, protocol version headers, localhost binding)
3. Phase 2: Core Schema Evolution (Titles, icons, tool annotations, structured output schemas)
4. Phase 3: New Content Types (Audio, resource links, content annotations)
5. Phase 4: Protocol Utilities (Logging, progress tracking, cancellation)
6. Phase 5: Client Features (Elicitation/Form mode, roots support, sampling)
7. Phase 6: Advanced Features (Experimental Tasks, Elicitation URL mode)

The MCP Framework implements a standard OAuth 2.1 flow with PKCE. The sequence of interactions is as follows:

1. Initial Request: Client attempts GET /messages without a token.
2. Challenge: Server returns 401 Unauthorized with WWW-Authenticate headers containing the authorization_uri and resource identifier.
3. Discovery: Client fetches metadata from /.well-known/oauth-protected-resource to identify authorization servers.
4. Authorization: Client initiates the flow via GET /authorize using PKCE (code_challenge).
5. Callback: After user authorization, the Authorization Server redirects to the server's /oauth/callback with a code and state.
6. Token Exchange: The server exchanges the code and code_verifier (PKCE) for an access_token via POST /token.
7. Authenticated Access: Client uses the access_token in the Authorization: Bearer header to successfully access protected resources.

You can enable MCP servers to pause tool execution and request structured user input from the client using the elicit() method within a tool. This uses the elicitation/create method in form mode, presenting the user with a schema-validated form.

Important Constraints:

• Flat Schemas Only: The schema must be a flat object. Nested objects and arrays are not supported (except for multi-select enums).
• Client Support: Always ensure the client supports the elicitation capability before calling elicit(). If the client does not support it, the server should throw an error: "Client does not support elicitation. Cannot request user input."
• Security: Do not use elicitation to request sensitive data like passwords or API keys.
• Response Handling: You must handle three possible user actions: accept, decline, and cancel.

// Inside a class extending BaseTool
protected async elicit(
  message: string,
  requestedSchema: {
    type: 'object';
    properties: Record<string, ElicitationFieldSchema>;
    required?: string[];
  }
): Promise<ElicitationResult> {
  // Implementation uses this.server.request with method 'elicitation/create'
}

The MCP Framework handles resource discovery automatically through two primary methods:

1. Auto-discovery

If you place your resource classes in src/resources/ (or any nested subdirectories) and use export default for each class, the framework will automatically discover and register them at startup. When a client calls resources/list, these resources will be included in the response.

2. Programmatic Registration

You can manually register resources using server.addResource(ResourceClass) before calling server.start().

Note: If a resource is both auto-discovered and programmatically registered with the same URI, the programmatic registration takes precedence.

import { MCPServer } from "mcp-framework";

const server = new MCPServer({ name: "my-server", version: "1.0.0" });

server.addResource(ConfigResource);
server.addResource(MarketDataResource);

await server.start();

When providing annotations, the framework performs soft validation (logging warnings) rather than rejecting or clamping values. This ensures compatibility with various server implementations.

Validation Rules

• priority: Expected range is 0.0 to 1.0. If a value is outside this range (e.g., -0.1 or 1.5), a warning is logged, but the value is still passed through to the response.
• lastModified: Expected to be an ISO 8601 timestamp (e.g., 2025-01-12T15:00:58Z or 2025-01-12). If the string is not parseable, a warning is logged, but the value is passed through.
• audience: Must contain only 'user' or 'assistant'. If other values are provided, a warning is logged.

Edge Cases

• Empty Audience: An empty array audience: [] is treated as unspecified. It is recommended not to emit an empty array in the final output.
• Resource Definitions vs. Content: Annotations can exist on both the resource definition (the metadata describing the resource) and the resource content (the actual data returned when reading a resource). These values can differ.
• Missing Annotations: If no annotations are provided, the annotations field will be absent from the output.