MCP Architecture Toolkit

A robust TypeScript library designed for constructing high-performance Model Context Protocol (MCP) backend services.

Modifications from Preceding Version

This specific iteration (@ronangrant/mcp-framework) incorporates the following key enhancements: - Shifted all operational logging output exclusively to the console stream, boosting general compatibility and stability. - Decoupled the system from reliance on the local file system for persistence of log data, thereby eliminating potential ENOENT exceptions. - Log implementation has been streamlined while preserving the established functional interface. - All emitted diagnostic information is now directed exclusively to standard error (stderr) via console.error().

Setup Instructions

To incorporate this toolkit into your project:

bash npm install @ronangrant/mcp-framework

Initialization Example

To spin up a new MCP service instance:

typescript import { MCPServer } from '@ronangrant/mcp-framework';

const serviceInstance = new MCPServer({ name: "my-production-service", version: "2.1.0" });

await serviceInstance.start();

Core Capabilities

• Intuitive programming interface for initializing MCP server infrastructure.
• Native scaffolding for managing tooling, context prompts, and associated data resources.
• Streamlined console-based diagnostics system.
• Superior development experience powered by full TypeScript type safety.
• Versatile options for handling network communication protocols (transports).

Licensing

Licensed under the MIT agreement.

MCP-Architect-Toolkit provides the foundational structure needed to elegantly engineer Model Context Protocol (MCP) services using modern TypeScript practices.

This toolkit supplies ready-made architecture, featuring automated scanning of directories for the instantiation of tools, resource definitions, and prompt templates. Leverage our powerful MCP abstraction layer to define these components with clean, expressive syntax. Furthermore, the included command-line utility drastically accelerates the initial setup process for your MCP service infrastructure.

Key Features

• 🛠️ Automatic discovery and dynamic loading of defined tools, resources, and prompt artifacts.
• Support across multiple communication substrates (e.g., stdio, Server-Sent Events (SSE)).
• Design philosophy prioritizes TypeScript, ensuring comprehensive compile-time type verification.
• Built atop the official MCP SDK specification.
• Provided base classes that simplify the creation of specialized tools, prompts, and resources.
• Integrated, pre-configured authentication mechanisms for SSE interfaces.

Consult the comprehensive documentation here

Generating a New Repository Structure with mcp-architect-toolkit

Utilizing the CLI (Recommended Path)

bash

Install the toolkit globally for utility access

npm install -g mcp-framework

Initiate scaffolding for a new MCP project

mcp create my-new-service-repository

Navigate into the newly generated directory

cd my-new-service-repository

Your foundational service structure is now complete!

CLI Operational Commands

The toolkit furnishes a powerful CLI utility for managing the lifecycle and structure of your MCP service projects:

Project Initialization

bash

Generate a new project structure

mcp create

Adding a Utility Function (Tool)

bash

Inject a new execution tool named 'price-fetcher'

mcp add tool price-fetcher

Adding a Contextual Directive (Prompt)

bash

Inject a new prompt template for 'price-analysis'

mcp add prompt price-analysis

Adding a Data Source (Resource)

bash

Inject a new data resource definition 'market-data'

mcp add resource market-data

Standard Development Cycle

1. Establish the project baseline:

bash mcp create my-service-project cd my-service-project

1. Augment functionality by adding necessary tools:

bash mcp add tool input-validator mcp add tool calculation-engine mcp add tool output-formatter

1. Compile the source code:

bash npm run build

1. Integrate with the target MCP Client (Refer to the Claude Desktop example below for guidance).

Integration with Claude Desktop Environment

Local Execution Setup

Insert the following configuration block into your Claude Desktop configuration file:

MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json` Windows: `%APPDATA%/Claude/claude_desktop_config.json`

{ "mcpServers": { "${projectName}": { "command": "node", "args":["/absolute/path/to/${projectName}/dist/index.js"] } } }

Post-Publication Setup

If deploying the service through a package manager, update your Claude Desktop configuration as follows:

MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json` Windows: `%APPDATA%/Claude/claude_desktop_config.json`

{ "mcpServers": { "${projectName}": { "command": "npx", "args": ["${projectName}"] } } }

Build and Verification Steps

1. Modify or create your required execution tools.
2. Execute `npm run build` to transpile and bundle the assets.
3. The server process will automatically load and register all tools upon subsequent startup.

Accelerated Start Guide

Defining a Custom Tool

typescript import { MCPTool } from "mcp-framework"; import { z } from "zod";

interface OperationParameters { instruction: string; }

class UtilityExecutor extends MCPTool { name = "utility_executor"; description = "A generalized utility for message transformation";

schema = { instruction: { type: z.string(), description: "The data string subject to transformation", }, };

async execute(input: OperationParameters) { return Transformed output: ${input.instruction.toUpperCase()}; } }

export default UtilityExecutor;

Server Initialization Boilerplate

typescript import { MCPServer } from "mcp-framework";

// Defaulting to standard I/O communication: const serverInstance = new MCPServer();

// ALTERNATIVELY: Utilizing the Server-Sent Events (SSE) transport protocol const serverInstance = new MCPServer({ transport: { type: "sse", options: { port: 8080 // Default listener port: 8080 } } });

// Activate the server listener await serverInstance.start();

Transport Configuration Details

Standard I/O Transport (Default Selection)

This transport is invoked automatically when no explicit configuration is provided:

typescript const serverInstance = new MCPServer(); // Explicit declaration is also possible: const serverInstance = new MCPServer({ transport: { type: "stdio" } });

Server-Sent Events (SSE) Transport

To enable the SSE communication layer:

typescript const serverInstance = new MCPServer({ transport: { type: "sse", options: { port: 8080, // Primary connection port (Default: 8080) endpoint: "/events", // Default path for the stream: "/sse" messageEndpoint: "/data-stream", // Default path for raw messages: "/messages" cors: { allowOrigin: "", // Default: "" allowMethods: "GET, POST, OPTIONS", // Default: "GET, POST, OPTIONS" allowHeaders: "Content-Type, Authorization, x-api-key", // Default list exposeHeaders: "Content-Type, Authorization, x-api-key", // Default list maxAge: "86400" // Default: "86400" seconds } } } });

Cross-Origin Resource Sharing (CORS) Configuration

The SSE transport offers granular control over CORS policies. While permissive settings are provided by default for rapid development, production environments necessitate stricter constraints defined here:

typescript const serverInstance = new MCPServer({ transport: { type: "sse", options: { // Restricting access to a specific web origin cors: { allowOrigin: "https://production-frontend.net", allowMethods: "GET, POST", allowHeaders: "Content-Type, Authorization", exposeHeaders: "Content-Type, Authorization", maxAge: "3600" } } } });

// Alternatively, allowing access from a list of authorized origins const serverInstance = new MCPServer({ transport: { type: "sse", options: { cors: { allowOrigin: "https://app-a.corp, https://app-b.corp", allowMethods: "GET, POST, OPTIONS", allowHeaders: "Content-Type, Authorization, Custom-Header", exposeHeaders: "Content-Type, Authorization", maxAge: "86400" } } } });

Security and Authentication Features

MCP Framework implements optional, pluggable security validation specifically for SSE endpoints. You can select between JSON Web Token (JWT) validation, static API Key checking, or substitute with a fully custom authentication provider implementation.

JWT Validation Integration

typescript import { MCPServer, JWTAuthProvider } from "mcp-framework"; import { Algorithm } from "jsonwebtoken";

const serverInstance = new MCPServer({ transport: { type: "sse", options: { auth: { provider: new JWTAuthProvider({ secret: process.env.SIGNING_SECRET, algorithms: ["HS256" as Algorithm], // Default: ["HS256"] headerName: "AuthorizationToken" // Default: "Authorization" }), endpoints: { sse: true, // Enforce protection on the stream connection (Default: false) messages: true // Enforce protection on payload messages (Default: true) } } } } });

Client requests must present a valid JWT within the specified header:

AuthorizationToken: Bearer eyJhbGciOiJIUzI1NiIs...

Static API Key Authentication

typescript import { MCPServer, APIKeyAuthProvider } from "mcp-framework";

const serverInstance = new MCPServer({ transport: { type: "sse", options: { auth: { provider: new APIKeyAuthProvider({ keys: [process.env.STATIC_ACCESS_KEY], headerName: "Service-Auth-Key" // Default: "X-API-Key" }) } } } });

Clients must present one of the registered keys in the Service-Auth-Key header:

Service-Auth-Key: your-static-secret-key-value

Implementing Custom Authentication Logic

You achieve customized request validation by implementing the AuthProvider contract:

typescript import { AuthProvider, AuthResult } from "mcp-framework"; import { IncomingMessage } from "node:http";

class CustomRequestValidator implements AuthProvider { async authenticate(request: IncomingMessage): Promise { // Insert proprietary authentication logic here (e.g., custom header check, session lookup) return false; // Return false or an AuthResult object on failure }

getAuthError() { return { status: 403, message: "Access denied by custom policy" }; } }

License

MIT