mcp-server

MCP Server (Model Context Protocol Server) is a general-purpose, modular server for implementing the Model Context Protocol (MCP). This project aims to provide a framework for controlling and interacting with various models through a standardized API.

Key Capabilities

• Modular architecture for easy extension
• Dynamic module loading
• Core model management functionality
• Standardized model context API
• Simple configuration system
• Logging utilities
• Enhanced module structure with proper separation of concerns
• Support for module package.json with dependency management
• Comprehensive testing infrastructure using Mocha and Chai
• Powerful module search functionality
• Module metadata displayed in API responses
• Integration with real AI model providers (OpenAI, Stability AI, Anthropic, Hugging Face)
• Support for text generation, image generation, and speech-to-text models
• Streaming inference support for compatible models

Usage

Requirements

• Node.js 18.x or higher
• pnpm 10.x or higher

This project uses ES Modules (ESM) only. All imports use import syntax rather than require().

Running the Server

By default, the server will start on http://localhost:3000 . Copy the example environment file and edit the API keys: At minimum, you need to add the API key for the model provider you want to use. API key acquisition addresses:

• OpenAI: https://platform.openai.com/api-keys
• Stability AI: https://platform.stability.ai/account/keys
• Anthropic: https://console.anthropic.com/settings/keys

The server has no global authentication layer, so anything that can access the port can call any module route. Modules that involve the file system or make outbound requests are subject to the following constraints:

• Module tokens: Routes with side effects accept tokens via Authorization: Bearer <token> or X-API-Key: <token>. When the variable is not set, routes remain open and a warning is logged at startup.
• Path containment: readme-badges resolves readmePath and rootDir based on README_BADGES_ROOT (default: working directory), and rejects anything that escapes, targets a non-markdown file, or reaches outside via symbolic links. scanner similarly confines exports to its report directory.
• Outbound request allowlist: Modules that fetch caller-named URLs reject loopback, link-local (cloud metadata), RFC1918, CGNAT, and other non-public addresses, resolve hostnames and check every returned address, and revalidate every redirect hop. When a module communicates with a known service, the host is also allowlisted.
• Cross-origin requests: CSRF_PROTECTION_ENABLED (default true) rejects state-changing requests carrying a foreign Origin header, so malicious web pages cannot drive a browser to access a locally bound server. Clients that do not send Origin (curl, MCP clients, server-to-server calls) are unaffected. List trusted browser origins in CORS_ORIGINS. If the server is exposed beyond localhost, run it behind an authenticating reverse proxy.

Testing the Server

The repository includes comprehensive tests using Mocha and Chai: The test infrastructure includes:

• Core server tests (module loading, routing, and other core functionality)
• Module-specific tests for each module's functionality
• Support for ES modules in tests
• Mocking and stubbing utilities using Sinon Test organization:
• Core tests are in /test/core/
• Module tests are in each module's test/ directory

Pre-commit Hooks

The repository includes pre-commit hooks using Husky and lint-staged:

• Runs ESLint on JavaScript files
• Runs Prettier on all staged files

Docker Support

ReposiThe library includes Docker support for easy containerization and deployment:

• Uses Node.js 20 Alpine as the base image
• Exposes port 3000
• Mounts the modules directory as a volume for easy module management
• Includes a health check

Standard MCP Methods

The MCP server implements a set of standardized methods that all MCP servers should provide:

Server Information

• GET / - Basic server information
• GET /status - Detailed server status
• GET /health - Health check endpoint
• GET /metrics - Server metrics

Model Management

• GET /models - List available models
• GET /model/:modelId - Get model information
• POST /model/:modelId/activate - Activate a specific model
• POST /model/deactivate - Deactivate the current model
• GET /model/active - Get active model information
• POST /model/infer - Perform inference using the active model
• POST /model/:modelId/infer - Perform inference using a specific model

Examples of supported model types:

• Text generation using GPT-4
• Image generation using Stable Diffusion
• Streaming text generation

Module Management

• GET /modules - List installed modules
• GET /modules/:moduleId - Get module information
• GET /modules/search/:query - Search modules by any field in package.json or metadata

Tools and Resources

• GET /tools - List available tools
• GET /resources - List available resources

Configuration

Configuration is loaded from environment variables and stored in src/core/config.js. The simplest way to configure is to edit the .env file in the project root directory. For key environment variables, see the complete list of configuration options in sample.env.

Examples

The repository contains several examples to help you get started:

• Client example: examples/client.js demonstrates how to use a client applicationto interact with the MCP server.
• Custom module example: examples/custom-module/ shows how to create a custom module that adds a calculator tool to the server. Run the client example: (specific commands not yet provided) To use the custom module example, copy it to the modules directory: (specific commands not yet provided)

Creating Modules

Modules are the primary way to extend the MCP server. Each module is a self-contained package that can add new functionality to the server.

Module Structure

Modules follow an enhanced structure with better organization. Each module should contain a package.json file with:

• Name, version, description
• Author and license information
• Dependencies and dev dependencies
• Scripts (especially tests)
• Keywords and other metadata

Module Implementation

The main module file (index.js) must export a register function, which is called when the module is loaded.

Example Modules

• Simple example module in mcp_modules/example/
• Complex example with a calculator tool in examples/custom-module/
• Health check module in mcp_modules/health-check/
• New module template in mcp_modules/template/

Creating a New Module

You can use the provided script to create a new module. The script will:

• Create a new module directory in mcp_modules/
• Copy the template files
• Replace placeholders with module information
• Provide next steps for implementing the module

Module Search

The MCP server includes powerful search functionality that allows you to find modules based on any information in package.json or metadata.

Search Endpoint

• GET /modules/search/:query - Search for modules containing the specified query string in any field Search comprehensively matches any field, including nested objects such as dependencies, keywords, and other metadata.

Model Providers

The MCP server integrates multiple AI model providers:

• OpenAI provides GPT models for text generation and Whisper for speech-to-text
• Stability AI provides Stable Diffusion for image generation
• Anthropic provides Claude models for text generation
• Hugging Face provides access to thousands of open-source models

Documentation

• MCP Standard Methods: Documentation of standard methods that all MCP servers should implement.
• MCP Interface: TypeScript interface definitions for the MCP protocol.
• Architecture: Overview of the MCP server architecture.