MCP Server

A Model Context Protocol (MCP) server for various data operations. Currently supports MongoDB operations with extensible architecture for additional data sources. See echo for a minimal example. Can be used in stdio mode or through http.

Quick Start

1. Ensure MongoDB is running (start it separately if needed)

2. Configure the server using a config.json file

   See Configuration below for details and examples.

3. Run the server (choose transport):

   # Stdio mode (default)
   go run main.go
   
   # HTTP mode
   go run main.go --transport=http

4. Configure VSCode MCP (choose transport):

   Stdio Transport:

   {
     "servers": {
       "mcp-server": {
         "command": "/path/to/mcp/mcp --config=/path/to/config/my-config.json",
         "cwd": "/path/to/mcp"
         "args": []
       }
     }
   }

   HTTP Transport:

   {
     "servers": {
       "mcp-server": {
         "type": "http",
         "url": "http://localhost:3001/mcp"
       }
     }
   }

Setup

1. Ensure you have Go 1.25+ installed
2. Run go mod tidy to download dependencies

Configuration

The server is configured using a config.json file in the same directory as the server.

Create a config.json file:

{
  "mongodb": {
    "enabled": true,
    "uri": "mongodb://username:password@localhost:27017?authSource=admin"
  },
  "echo": {
    "enabled": true
  },
  "server": {
    "port": 3001
  }
}

Service Configuration

You can enable or disable individual MCP services:

• mongodb.enabled: Set to true to enable MongoDB operations, false to disable
• mongodb.uri: MongoDB connection URI (database is specified per operation, not in URI)
• echo.enabled: Set to true to enable the echo service (for testing), false to disable
• server.port: Port for HTTP server (default: 3001)

This allows you to run only the services you need.

Running the Server

# Stdio mode (default) with default config
go run main.go

# HTTP mode with default config
go run main.go --transport=http

# Stdio mode with custom config file
go run main.go --config=my-config.json

# HTTP mode with custom config file
go run main.go --transport=http --config=/path/to/config.json

The HTTP server will start on the port specified in the config.json file (default: 3001).

Available Tools

• echo-hello: Echoes "Hello World!" (example tool)
• mongodb-list-collections: List all collections in the database
• mongodb-find: Query documents in a collection
• mongodb-insert-one: Insert a single document
• mongodb-update-one: Update a single document
• mongodb-delete-one: Delete a single document
• mongodb-insert-many: Insert multiple documents
• mongodb-update-many: Update multiple documents
• mongodb-delete-many: Delete multiple documents
• mongodb-count: Count documents in a collection
• mongodb-drop-collection: Drop (delete) an entire collection

Extensibility

The MCP server is designed to be extensible. To add support for additional data sources (PostgreSQL, Redis, etc.), simply:

1. Create a new service package with controller.go and model.go
2. Implement the protocol.ToolCaller interface
3. Add the controller to the main application in main.go
4. The server automatically discovers and exposes tools from all registered controllers

Example Usage

JSON-RPC Requests

Initialize the connection:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "test-client",
      "version": "1.0.0"
    }
  }
}

List available tools:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Call tools:

// Echo hello
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "echo-hello",
    "arguments": {}
  }
}

// List MongoDB collections
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "mongodb-list-collections",
    "arguments": {}
  }
}

// Find documents
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "mongodb-find",
    "arguments": {
      "collection": "users",
      "filter": {},
      "limit": 10
    }
  }
}

// Insert a document
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "mongodb-insert-one",
    "arguments": {
      "collection": "users",
      "document": {
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  }
}

Note: The update parameter in MongoDB operations supports partial field updates. Only specify the fields you want to change - the operation automatically uses $set to update only those fields without replacing the entire document.

MCP Protocol

The server implements the Model Context Protocol (MCP) over both stdio and HTTP transports:

• Stdio Transport: JSON-RPC messages over stdin/stdout (default)
• HTTP Transport: JSON-RPC messages over HTTP POST to /mcp endpoint

Supported MCP Methods:

• initialize: Initialize the MCP connection
• tools/list: List available tools
• tools/call: Execute a tool with parameters

All communication follows the JSON-RPC 2.0 specification with MCP-specific method extensions.

License

This project is licensed under the MIT License - see the LICENSE file for details.