MCP Server

A remote Model Context Protocol (MCP) server implementation that provides tools for AI assistants to interact with external services and perform various operations.

Overview

This MCP server implements the Model Context Protocol specification, allowing AI assistants to access custom tools and capabilities through a standardized JSON-RPC interface. The server runs on port 8000 and provides several built-in tools for basic operations and conversation archiving.

Features

• JSON-RPC 2.0 Protocol: Full implementation of the MCP specification
• Built-in Tools:
  • add: Perform basic arithmetic operations
  • reverse: Reverse text strings
  • save_conversation: Archive conversations to aiarchives.duckdns.org
• Health Monitoring: Built-in health check endpoint
• CORS Support: Cross-origin resource sharing enabled
• Error Handling: Comprehensive error handling with proper JSON-RPC error codes

Prerequisites

• Node.js (version 16 or higher)
• npm or yarn package manager

Usage

Configuring Claude Desktop

To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration file.

Finding the Configuration File

1. Open Claude Desktop
2. Go to Settings (gear icon in the bottom left)
3. Click on Advanced in the left sidebar
4. Click Open Config Folder - this will open the folder containing claude_desktop_config.json
5. Open the claude_desktop_config.json file in your preferred text editor

Adding the MCP Server Configuration

Add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "aiarchives": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://aiarchives.duckdns.org/mcp",
        "--allow-http",
        "--transport",
        "http-only"
      ]
    }
  }
}

Note: Make sure to restart Claude Desktop after making changes to the configuration file.

Server Access

This MCP server is hosted remotely and accessible at https://aiarchives.duckdns.org/mcp. Once you've configured Claude Desktop as described above, you can immediately start using the available tools without needing to run anything locally.

Note: The server is always running and ready to accept requests through the MCP protocol.

Local Deployment (Optional)

If you want to run the server locally for development or testing purposes:

1. Start the server:

   npm start
   

   Or run directly with Node.js:

   node server-mcp.js
   

2. Update the Claude Desktop configuration to point to your local server:

   {
     "mcpServers": {
       "aiarchives": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "http://localhost:8000/mcp",
           "--allow-http",
           "--transport",
           "http-only"
         ]
       }
     }
   }
   

Important: When running locally, the save_conversation tool will not work because it depends on the remote aiarchives API that's only available on the hosted server. The add and reverse tools will work normally.

Available Endpoints

POST /mcp

Main MCP protocol endpoint that handles JSON-RPC requests.

Example request:

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

GET /health

Health check endpoint that returns server status.

Response:

{
  "status": "healthy",
  "server": "Remote MCP Server",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

GET /mcp

Debug endpoint that confirms the server is running.

Available Tools

1. add

Performs addition of two numbers.

Parameters:

• a (number): First number
• b (number): Second number

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add",
    "arguments": {
      "a": 5,
      "b": 3
    }
  }
}

2. reverse

Reverses a text string.

Parameters:

• text (string): Text to reverse

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reverse",
    "arguments": {
      "text": "Hello World"
    }
  }
}

3. save_conversation

Saves conversation content to aiarchives.duckdns.org and returns a shareable URL.

Parameters:

• conversation (string): Full conversation content as HTML or plain text

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "save_conversation",
    "arguments": {
      "conversation": "<html><body>Conversation content...</body></html>"
    }
  }
}

MCP Protocol Methods

The server implements the following MCP protocol methods:

• initialize: Initialize the MCP connection
• tools/list: List available tools
• tools/call: Execute a specific tool
• notifications/initialized: Handle client initialization notification
• notifications/cancelled: Handle request cancellation notification

Error Handling

The server returns proper JSON-RPC 2.0 error responses with standard error codes:

• -32600: Invalid Request
• -32601: Method not found
• -32602: Invalid params
• -32603: Internal error

Development

Project Structure

mcp-server/
├── server-mcp.js      # Main server implementation
├── package.json       # Dependencies and scripts
├── .gitignore        # Git ignore rules
└── README.md         # This file

Adding New Tools

To add a new tool, modify the tools/list response and add a corresponding case in the tools/call switch statement in server-mcp.js.

Testing

Currently, there are no automated tests. You can test the server manually using curl or any HTTP client:

# Health check
curl http://localhost:8000/health

# List tools
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Dependencies

• express: Web framework for Node.js
• body-parser: Middleware for parsing request bodies
• cors: Cross-origin resource sharing middleware