mcp-framework: Directory Discovery and Build-Time Schema Validation for TypeScript MCP Servers

The problem mcp-framework solves: MCP servers are boilerplate-heavy

A Model Context Protocol server has to declare a name, a version, a capability set, a transport, and a request handler for every tool, resource and prompt. Written directly against the MCP SDK, that is a lot of registration code before you write any domain logic, and the registration code is the part you rewrite for every server. mcp-framework's answer is convention: files in a tools directory are discovered and loaded, each file exports a class extending MCPTool, and the framework handles the wiring. The README describes this as "automatic directory-based discovery for tools, resources, and prompts". The audience is a TypeScript developer who already knows what MCP is and wants to stop re-deriving the same server skeleton. If you are writing a single throwaway tool, the framework's conventions cost more than they save.

How the tool class and discovery mechanism fit together

A tool is a class with three required members and one method. The README example uses name, description and schema as fields and an async execute(input) method that returns a string. The schema field is a Zod object, and the input type is derived from the class itself via MCPInput<this>, so the execute signature follows whatever schema you declared rather than a hand-written interface. The framework then loads the class, reads name and description, converts the Zod schema to the JSON Schema that MCP clients consume, and routes calls to execute. That is the whole data flow, and it is the reason the validation step exists: the JSON Schema handed to a model is only as good as the descriptions attached to each field, and a Zod schema without .describe() produces a schema the model cannot interpret. The base classes for prompts and resources follow the same pattern, and the CLI's mcp add tool, mcp add prompt and mcp add resource commands generate the corresponding files.

Getting a server running: the mcp CLI and the generated layout

Install globally, then create:

npm install -g mcp-framework mcp create my-mcp-server cd my-mcp-server

That produces a project whose entry point is dist/index.js after a build. Adding a tool is mcp add tool price-fetcher, and the README's development loop is: edit tools, run npm run build, then node dist/index.js. The server validates its tools on startup before accepting connections, so a schema problem surfaces at launch as well as at build. Registering the server with Claude Desktop means editing claude_desktop_config.json, at ~/Library/Application Support/Claude/ on macOS or %APPDATA%/Claude/ on Windows, with a command of node and args pointing at the absolute path to dist/index.js. After publishing, the same block uses npx with the package name as the single argument. Environment variables cover logging: MCP_ENABLE_FILE_LOGGING (default false), MCP_LOG_DIRECTORY (default logs), and MCP_DEBUG_CONSOLE for debug-level console output.

Schema validation is the feature worth adopting, and it has a bypass

The build runs tool validation automatically. mcp validate checks that every field in every Zod object schema carries a description, and the README shows the failure output naming the file and the offending fields, then pointing at z.string().describe("..."). You can also call mcp validate standalone, and the README suggests wiring it into package.json as "test": "jest && mcp validate" or "prepack": "npm run build && mcp validate". This is a real constraint rather than a style preference: an undescribed field becomes an undescribed property in the schema the model sees, and the model then guesses. The escape hatch is MCP_SKIP_TOOL_VALIDATION=true, which the README flags as not recommended. Note the default: validation is on, so MCP_SKIP_TOOL_VALIDATION=false is the explicit form of the default behaviour. A team that sets the skip variable to unblock a build has disabled the framework's main quality gate and should say so in the commit message.

Transports: stdio is the default, HTTP is experimental and CORS is a wildcard

The README lists stdio, SSE and HTTP Stream as supported transports, and out-of-the-box authentication for SSE endpoints via OAuth 2.1, JWT and API key. The CLI defaults to stdio. The HTTP path is opt-in and described as EXPERIMENTAL: mcp create my-mcp-server --http --port 1337 --cors, where --port defaults to 8080 when omitted and --cors enables wildcard access. The README is direct about the consequence: "This will set cors allowed origin to \"*\", modify it in the index if you wish". Treat that as the framework telling you the generated configuration is a starting point, not a deployment posture. If your server is reachable from a browser and handles anything sensitive, the generated index needs editing before it goes anywhere. The authentication feature is scoped to SSE endpoints in the README's wording; it is not described as applying to the HTTP transport.

Where mcp-framework is the wrong choice

The version line is the first thing to weigh. The releases listed are 0.2.20 through 0.2.22, dated April 2026, with 0.2.20 and 0.2.21 two weeks apart. A 0.2.x series means the project has not declared a stable API, and the README itself calls the HTTP transport experimental. If you need a long-lived server with a frozen interface, that is a mismatch. The second case is a team that wants no build step: discovery here is directory-based and files are compiled to dist before the server runs, so a single-file server written against the MCP SDK directly has less machinery between you and the protocol. The third case is a server that needs transport behaviour the README does not describe. The material covers stdio, SSE and HTTP Stream and the authentication for SSE, but says nothing about the operational characteristics of the HTTP transport beyond the port and CORS flags, and nothing about how discovery behaves when two files export classes with the same tool name. That last question is worth answering with a two-file experiment before you rely on the convention.

The alternative: the official MCP SDK without the framework

The README states the framework is "Built on the official MCP SDK", which makes the SDK the natural comparison rather than a competitor. The difference is where the structure lives. With the SDK alone, you instantiate a server, declare its capabilities, and register each tool with a handler and a schema in one place, so the registration is explicit and greppable, and there is no discovery convention to learn or to debug when a file is not picked up. With mcp-framework, the structure lives in the filesystem and in base classes, and you get discovery plus the build-time description check in exchange for accepting the conventions and the CLI-generated layout. Neither is strictly better. The framework's validation gate has no equivalent in a bare SDK setup unless you write it, and the bare SDK has no discovery step that can silently miss a file. Pick the SDK if your server is small or if you want the registration visible in a single file; pick the framework if you expect the tool count to grow and you want the description check enforced on every build.

Maintenance cost and the MIT licence

The framework is MIT licensed, which permits commercial and closed-source use and requires that the licence text and copyright notice be preserved in distributions. That is a summary of the identifier, not legal advice; read the LICENSE file in the repository. The upgrade cost is tied to the 0.2.x line: minor-version bumps in a pre-1.0 series can change behaviour, and the README's own labelling of the HTTP transport as experimental is a signal that at least one surface is expected to move. Practically, that means pinning the version, reading the release notes between bumps, and keeping the build's validation step in CI so a schema regression fails the build rather than reaching a client. If you use the generated HTTP transport, the CORS origin edit in index.ts is a change you own after generation, and regenerating or copying the scaffold is how that edit gets lost.

Editorial conclusion

Adopt it if you are building a stdio MCP server in TypeScript and want the Zod description check enforced in CI, since that is the one feature here that catches a real class of bug at build time. Do not adopt it if you need a production HTTP endpoint today: the README labels that transport experimental and the --cors flag sets Access-Control-Allow-Origin to a wildcard that you have to edit by hand. Before committing, run mcp create in a scratch directory, confirm which transport the generated index.ts actually wires up, and decide whether you accept a 0.2.x version line as your dependency.

Official sources

1. License: MIT
2. Project website
3. QuantGeekDev/mcp-framework on GitHub
4. README
5. Releases