mcp-framework

Automatically discovers and registers Tools, Resources, and Prompts from filesystem directories without explicit configuration. The framework scans designated directories (tools/, resources/, prompts/), instantiates classes extending MCPTool, MCPResource, or MCPPrompt base classes, and registers them with the MCPServer instance. This eliminates boilerplate registration code and enables developers to add new capabilities by simply creating files in the correct directory structure.

Provides a unified transport abstraction layer supporting three communication protocols: stdio (for local/embedded use), Server-Sent Events/SSE (for long-lived HTTP connections), and HTTP streaming. The framework abstracts protocol differences behind a common interface, allowing developers to switch transports via configuration without changing tool/resource/prompt implementations. Each transport handles its own serialization, connection lifecycle, and message framing according to MCP specification requirements.

Implements HTTP streaming transport that allows MCP servers to communicate with clients over HTTP connections. The framework provides configuration options for HTTP endpoints, request/response handling, and streaming mechanics. Developers configure HTTP transport settings (port, path, authentication) and the framework handles serialization, connection management, and message framing according to MCP HTTP streaming specification.

Implements Server-Sent Events transport that enables long-lived HTTP connections between MCP clients and servers. SSE transport maintains persistent connections and streams MCP messages as server-sent events. The framework handles SSE connection lifecycle, event serialization, and reconnection logic. Developers configure SSE endpoints and authentication; the framework manages the rest.

Implements stdio transport that communicates with MCP clients via standard input/output streams. This transport is ideal for local development, CLI tools, and embedded scenarios where the MCP server runs as a subprocess. The framework handles message serialization over stdin/stdout, process lifecycle management, and error handling through stderr. Stdio transport requires no network configuration and is the default for Claude Desktop integration.

Enables developers to define tool inputs using JSON Schema, which the framework automatically validates against incoming requests before execution. Tools extend the MCPTool base class and declare their input schema; the framework validates all invocations against this schema, rejecting malformed requests before they reach tool code. This provides type safety at the protocol boundary and enables Claude to understand tool capabilities without executing them.

Provides three base classes (MCPTool, MCPResource, MCPPrompt) that developers extend to implement capabilities. Each base class defines a standard interface with name, description, schema (for tools), and an execute() method. This inheritance pattern ensures consistent structure across all components, enables the auto-discovery system to identify components, and provides type safety through TypeScript class hierarchies. Developers implement only the execute() method and metadata properties.

Provides optional authentication mechanisms for HTTP and SSE transports, allowing developers to secure MCP server endpoints. The framework supports authentication configuration at the transport level; authenticated requests must include valid credentials (e.g., API keys, bearer tokens) before the server processes them. Authentication is enforced before tool/resource/prompt execution, protecting the entire MCP interface.

Provides command-line tools for creating new MCP projects, managing project structure, building TypeScript code, and configuring deployment. The CLI scaffolds a complete project structure with directories for tools, resources, and prompts, initializes git repositories, installs dependencies, and builds the TypeScript project. Developers use CLI commands to create projects, add components, and manage the build process without manual configuration.

Enables developers to define Resources that provide Claude with access to external data sources (files, APIs, databases) through a standardized interface. Resources extend the MCPResource base class and implement an execute() method that retrieves data from external sources. The framework manages resource lifecycle and exposes resources to Claude, allowing it to request data without directly accessing external systems.

Allows developers to define Prompts that provide Claude with pre-written instructions, context, or templates for specific tasks. Prompts extend the MCPPrompt base class and are automatically discovered and registered. Claude can request prompts by name, receiving the pre-defined content to guide its behavior. This enables developers to inject domain-specific instructions into Claude without modifying Claude's system prompt.

The entire framework is built in TypeScript and enforces type safety throughout the development experience. All components (Tools, Resources, Prompts) are defined as TypeScript classes with typed properties and methods. The framework provides type definitions for MCP protocol messages, transport configuration, and component interfaces. Developers get IDE autocomplete, compile-time type checking, and runtime type safety without additional validation code.

The framework is built on top of the official @modelcontextprotocol/sdk, ensuring full compliance with the MCP specification. The framework wraps SDK functionality with higher-level abstractions (base classes, auto-discovery, CLI tools) while delegating protocol handling to the official SDK. This ensures that all MCP protocol requirements are met and the framework stays synchronized with specification updates.