MCP-Framework

Tools are defined as TypeScript classes extending MCPTool<T> with Zod schemas that enforce compile-time and runtime type safety. The framework automatically generates JSON schemas from Zod definitions, validates all inputs against the schema before execution, and provides full TypeScript IntelliSense for tool parameters. This eliminates manual schema-to-code synchronization and catches type mismatches at both development and runtime.

The framework automatically discovers and registers tools by scanning the `tools/` directory for TypeScript files, eliminating manual tool registration. Each file in the directory is expected to export a class extending MCPTool, which the framework instantiates and registers without explicit configuration. This directory-based convention reduces boilerplate and allows developers to add new tools by simply creating a new file in the designated directory.

Prompt templates are auto-discovered from files in the `prompts/` directory and exposed to MCP clients. The framework scans the directory and registers prompts without explicit configuration. Implementation details for prompt definition, templating syntax, and parameter handling are not documented.

The framework includes pre-configured build tooling (TypeScript compilation, bundling, dependency management) that enables developers to start a working MCP server in under 5 minutes. The scaffolding generates a complete project with package.json, tsconfig.json, and build scripts, eliminating manual build configuration. Developers can run `npm start` or equivalent to launch the server immediately after scaffolding.

The framework provides an abstraction layer supporting multiple transport mechanisms (stdio, Server-Sent Events/SSE, HTTP streaming) for MCP protocol communication. Developers define tools once and the framework handles serialization, deserialization, and protocol-specific communication details across all transports. This allows the same tool collection to be exposed via different communication channels without code changes.

The framework includes native authentication providers for OAuth 2.1, JWT, and API key validation, allowing developers to protect tool endpoints without implementing authentication from scratch. Providers are configured declaratively and applied to tools, with the framework handling token validation, expiration checking, and credential extraction from requests. Custom auth providers can be implemented by extending the base provider interface.

The framework provides a CLI tool (`mcp create app`, `mcp add tool`) that generates TypeScript project scaffolding and tool boilerplate. Running `mcp create app` creates a complete MCP server project with build configuration, dependencies, and example tools. The `mcp add tool` command generates a new tool class with schema template and execute method stub, reducing manual setup time.

The framework implements the Model Context Protocol (MCP) server specification, exposing tools, resources, and prompts to MCP-compatible clients (Claude Desktop, Cursor, etc.). Tools are the primary capability with full implementation; resources and prompts are mentioned as auto-discoverable from `resources/` and `prompts/` directories but lack documented implementation details. The framework handles all MCP protocol compliance, message serialization, and client communication.

The framework is built exclusively for TypeScript, providing compile-time type checking, full IDE IntelliSense for tool parameters and outputs, and type inference from Zod schemas. Tool definitions are generic types (MCPTool<typeof schema>) that enforce schema-implementation coupling at compile time, catching type mismatches before runtime. All framework APIs are fully typed with no any types.

The framework supports custom middleware for processing requests and responses, allowing developers to add cross-cutting concerns like logging, metrics, request transformation, and response formatting. Middleware is composable and executes in a defined order around tool execution. Implementation pattern for custom middleware is mentioned but not documented, requiring developers to infer the API from examples or source code.

Tools implement an async execute() method that returns results in MCP-compliant format ({ content: [...] }). The framework handles async execution, error handling, and response serialization. Tool execution is non-blocking, allowing multiple concurrent tool calls. The response format is fixed and standardized, ensuring compatibility with all MCP clients.

Resources are auto-discovered from files in the `resources/` directory, similar to tools and prompts. The framework scans the directory and registers resources without explicit configuration. Implementation details for resource definition and structure are not documented, making it unclear how to define resources or what formats are supported.