README - Model Context Protocol (MCP) Server by infinyte

Model Context Protocol (MCP) Server

A simple server implementation for the Model Context Protocol that provides a unified API for multiple AI model providers.

Features

Unified API for multiple AI providers (Anthropic, OpenAI)
Support for chat completions and legacy completions
Tool calling support
Context/system message handling
Environment-based configuration
MongoDB database for persistence and state management
Tool execution history and analytics

Installation

# Clone the repository
git clone <repository-url>
cd testmcp

# Install dependencies
npm install

# Run the interactive setup
npm run setup

The setup script will guide you through configuring the necessary API keys:

ANTHROPIC_API_KEY - For Claude models
OPENAI_API_KEY - For GPT models and DALL-E image generation
STABILITY_API_KEY - For Stable Diffusion image generation
GOOGLE_CSE_API_KEY and GOOGLE_CSE_ID - For web search functionality
BING_SEARCH_API_KEY - For fallback web search

You can also manually edit the .env file if you prefer.

MongoDB Setup

The MCP server uses MongoDB for data persistence. You have several options for setting up MongoDB:

Option 1: Automated Setup (Recommended)

Run the MongoDB setup script, which will guide you through the process:

# Run the MongoDB setup script
npm run setup-mongodb

This script will:

Check if Docker is available
Start MongoDB using Docker Compose (if available)
Configure the connection in your .env file
Verify the MongoDB connection

Option 2: Manual Docker Setup

The easiest way to get started with MongoDB is to use the included Docker Compose configuration:

# Start MongoDB and Mongo Express in Docker
docker compose up -d

# Update your .env file with the connection string
echo "MONGODB_URI=mongodb://mcpuser:mcppassword@localhost:27017/mcp-server" >> .env

MongoDB will be available at mongodb://mcpuser:mcppassword@localhost:27017/mcp-server
Mongo Express (web admin) will be available at http://localhost:8081

Option 3: Local MongoDB Installation

If you prefer to install MongoDB locally:

Install MongoDB from https://www.mongodb.com/try/download/community
Start the MongoDB service

Update your .env file with:

MONGODB_URI=mongodb://localhost:27017/mcp-server

Option 4: MongoDB Atlas (Cloud)

For production use, MongoDB Atlas is recommended:

Create an account at https://www.mongodb.com/cloud/atlas
Create a new cluster
Set up a database user and whitelist your IP address

Get your connection string and update your .env file:

MONGODB_URI=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/mcp-server?retryWrites=true&w=majority

Database Migration

To migrate existing data to MongoDB:

# Run the migration script
npm run migrate-mongodb

This script will:

Migrate tool definitions to MongoDB
Migrate configurations (like API keys) to MongoDB
Import any backup data if available

Usage

Start the server

# Interactive startup (checks for API keys)
npm start

# Development mode with auto-reload
npm run dev

# Quick start (skips environment checks)
npm run quick-start

# Start server with PM2 process manager
npm run pm2:start

# Start server with PM2 in production mode
npm run pm2:start:prod

The server will be running at http://localhost:3000 (or the port you specified in .env).

Startup Options

Standard Start (npm start):
- Checks if API keys are configured
- Prompts for setup if no keys are found
- Recommended for first-time users
Development Mode (npm run dev):
- Uses nodemon for auto-reload on code changes
- Still performs environment checks
- Best for development
Quick Start (npm run quick-start):
- Bypasses all environment checks
- Starts the server immediately
- Useful when you know your configuration is correct
PM2 Production Mode (npm run pm2:start:prod):
- Runs the server using the PM2 process manager
- Automatically restarts if the server crashes
- Optimized for production environments
- Bypasses environment checks

Using PM2 Process Manager

The server can be run with PM2, a production process manager for Node.js applications. PM2 provides features like:

Process management (restart on crash)
Log management
Performance monitoring
Load balancing (for multiple instances)

PM2 Commands

# Start the server with PM2
npm run pm2:start

# Start in production mode
npm run pm2:start:prod

# View logs
npm run pm2:logs

# Monitor performance
npm run pm2:monit

# Restart the server
npm run pm2:restart

# Stop the server
npm run pm2:stop

# Remove the server from PM2
npm run pm2:delete

The PM2 configuration is stored in ecosystem.config.js. You can modify this file to change:

Process name
Environment variables
Memory limits
Deployment configuration
Number of instances (for load balancing)

API Endpoints

`POST /mcp/:provider`

Make requests to AI models through a unified API.

URL Parameters:

provider: The AI provider to use (anthropic or openai)

Request Body:

{
  "messages": [
    { "role": "user", "content": "Your prompt here" }
  ],
  "model": "claude-3-opus-20240229",  // Optional, provider-specific model name
  "tools": [...],  // Optional, tools for function calling
  "context": "System message or context"  // Optional
}

OR (Legacy format):

{
  "prompt": "Your prompt here",
  "model": "claude-3-opus-20240229",  // Optional
  "context": "System message or context"  // Optional
}

Response: Returns the raw response from the provider's API.

`GET /tools/available`

Get a comprehensive list of all available tools with detailed information.

Query Parameters:

format - Response format: json (default), yaml, table, or html
category - Filter tools by category (optional)
enabled - Filter by enabled status: true (default) or false
search - Search for tools by name, description, or tags
provider - Filter tools by provider (e.g., openai, google)
limit - Maximum number of tools to return (for pagination)
offset - Offset for pagination (default: 0)

Response (JSON format):

{
  "success": true,
  "count": 10,
  "metadata": {
    "categories": ["web", "image", "utility"],
    "providers": ["openai", "anthropic", "internal"],
    "totalCount": 24,
    "offset": 0,
    "limit": 10
  },
  "tools": [
    {
      "name": "web_search",
      "description": "Search the web for information",
      "category": "web",
      "version": "1.0.0",
      "provider": "google",
      "enabled": true,
      "parameters": {
        "query": {
          "type": "string",
          "description": "The search query",
          "required": true
        },
        "limit": {
          "type": "number",
          "description": "Maximum number of results",
          "required": false,
          "default": 5
        }
      },
      "usage": {
        "endpoint": "/tools/web/search",
        "method": "POST",
        "parameters": { /* same as above */ }
      },
      "metadata": {
        "createdAt": "2023-10-15T12:00:00Z",
        "updatedAt": "2024-04-20T09:30:00Z",
        "usageCount": 1245
      }
    }
    // ... more tools
  ]
}

`GET /health`

Health check endpoint that returns status 200 if the server is running.

Data Management

Database Backups

You can create and manage database backups:

# Create a full backup
npm run backup-mongodb

# Create a backup with execution history
npm run backup-mongodb -- --with-executions

# List existing backups
npm run backup-mongodb -- --list

Testing the Database Connection

To verify your MongoDB setup:

# Run the database test script
npm run test-mongodb

Example Clients

Command Line Client

A test client is included in src/client.js. To run it:

node src/client.js

Web Client

A simple web interface is available at http://localhost:3000 when the server is running. You can use this to test the API directly from your browser.

Available Tools

The MCP server provides a tools discovery endpoint that allows users and AI agents to programmatically list all available tools:

Tools Discovery

GET /tools/available - Lists all available tools with detailed information.

Supports multiple formats: JSON, YAML, HTML, and ASCII table
Provides filtering by category, provider, and search terms
Includes detailed metadata and usage examples for each tool

Example usage:

# Get all tools in JSON format
curl http://localhost:3000/tools/available

# Get tools in a specific category
curl http://localhost:3000/tools/available?category=web

# Search for image-related tools
curl http://localhost:3000/tools/available?search=image

# Get a formatted HTML page of all tools
curl http://localhost:3000/tools/available?format=html > tools.html

Web Search Tools

The server includes built-in web search and retrieval tools:

Web Search (/tools/web/search)
- Search the web for information on a given query
- Parameters: query (required), limit (optional)
- Requires: GOOGLE_CSE_API_KEY and GOOGLE_CSE_ID environment variables
- Falls back to BING_SEARCH_API_KEY if Google search fails
Web Content (/tools/web/content)
- Retrieve and extract content from a specific URL
- Parameters: url (required), useCache (optional)
Web Batch (/tools/web/batch)
- Retrieve content from multiple URLs in parallel
- Parameters: urls (required array), useCache (optional)

Image Generation Tools

The server also includes image generation, editing, and variation tools:

Generate Image (/tools/image/generate)
- Generate an image based on a text prompt
- Parameters:
  - prompt (required): Detailed description of the image
  - provider (optional): openai or stability (defaults to openai)
  - options (optional): Provider-specific options
Edit Image (/tools/image/edit)
- Edit an existing image with a text prompt
- Parameters:
  - imagePath (required): Path to the image to edit
  - prompt (required): Description of the edit to make
  - maskPath (optional): Path to a mask image
Create Image Variation (/tools/image/variation)
- Create a variation of an existing image
- Parameters:
  - imagePath (required): Path to the image to create variations of

Note: To use these tools, you need to set API keys in your .env file:

For OpenAI images: OPENAI_API_KEY

For Stability AI images: STABILITY_API_KEY

For Web Search: GOOGLE_CSE_API_KEY and GOOGLE_CSE_ID

Tool Integration with AI Models

The MCP server automatically handles tool calling and execution with AI models. When a model decides to use a tool, the server:

Executes the requested tool with the provided parameters
Returns the tool's response to the model
The model can then incorporate the tool's response into its final answer

Tool Discovery for AI Models

AI models can use the /tools/available endpoint to discover what tools are available and how to use them. This is particularly useful for:

Dynamic tool discovery during runtime
Self-documentation for AI agents
Enabling AI systems to adapt to available capabilities

Example system prompt for AI models:

You have access to external tools through the MCP server. 
Before using any tools, you should check what tools are available by calling:
GET /tools/available

This will return a list of all available tools with their parameters and usage instructions.
You can then use these tools by following the provided usage patterns.

Example Tool Usage

See the /examples directory for sample code demonstrating tool usage.

Adding New Providers or Tools

Adding New AI Providers

To add new AI providers:

Add the provider's SDK to the project
Create a new handler function in server.js
Add a new case in the main route handler

Adding New Tools

To add new tools to the server:

Create a new tool implementation in the /src/tools directory
Add the tool definition to tool-definitions.js
Update the tool execution functions in server.js
Add new API endpoints for direct tool usage (if needed)

License

ISC