A Model Context Protocol (MCP) implementation showcasing clean, modular tool architecture with local and remote tools support and an interactive browser client.

• 🏗️ Clean Architecture: Modular tool design with MCPToolsManager
• 🔧 8 Demo Tools: 4 local + 4 remote tools working seamlessly together
• 🌐 Remote Tools Support: Load tools dynamically from external APIs
• 🌐 Browser Client: Interactive web interface for testing all tools
• 🔧 Admin Panel: Powerful web-based tool management with on/off toggles
• ⚡ Tool Configuration: JSON-based tool state management with persistence
• 📡 Multiple Server Options: Stdio, Simple HTTP, and Remote Tools servers
• 🔒 Type Safety: Full TypeScript implementation with Zod validation

git clone <your-repo-url>
cd mcp-hello-world
npm install

Start both servers for the complete experience:

# Terminal 1: Start remote tools server (4 remote tools)
npm run start:remote

# Terminal 2: Start HTTP server (4 local + 4 remote = 8 total tools)
npm run start:http

Then open:

• Client Interface: http://localhost:3000/examples/client.html
• Admin Panel: http://localhost:3000/examples/admin.html

# Just local tools (4 tools)
REMOTE_TOOLS_ENABLED=false npm run start:http

npm run build
node dist/index.js  # Stdio MCP server

mcp-hello-world/
├── src/
│   ├── index.ts                 # Main MCP stdio server
│   ├── mcp-tools-manager.ts     # Generic tools manager (local + remote)
│   ├── simple-http-server.ts    # HTTP wrapper with remote tools support
│   ├── tool-config.ts          # 🔧 Tool configuration manager
│   ├── tools/                   # 🏠 Local tools directory
│   │   ├── index.ts            # Tools exports and registry
│   │   ├── greg-test-tool.ts   # Mood testing tool
│   │   ├── http-post-tool.ts   # Generic HTTP POST
│   │   ├── weather-tool.ts     # Weather API integration
│   │   └── create-post-tool.ts # JSONPlaceholder posts
│   └── types/mcp.ts            # TypeScript definitions
├── examples/
│   ├── client.html             # 🌐 Interactive browser client
│   ├── admin.html              # 🔧 Admin panel for tool management
│   ├── remote-tools-api-example.json      # Remote tools definition
│   └── remote-tool-server-example.js     # 🌐 Remote tools server
├── tool-config.json            # ⚡ Tool configuration state
└── dist/                       # Compiled JavaScript

• Single Source of Truth: Local tools in src/tools/, remote tools via API
• Generic Manager: MCPToolsManager automatically loads all tools
• Tool Configuration: JSON-based persistent tool state management
• Hot-loadable: Remote tools can be added/updated without restart
• Multiple Interfaces: Same tools work with stdio, HTTP, and browser
• Admin Control: Web-based tool management with real-time toggles

1. 🎭 Greg Test (greg-test) - Mood testing tool
2. 🌐 HTTP POST (http_post) - Generic HTTP requests
3. 🌤️ Weather (get_weather) - Weather API with OpenWeatherMap
4. 📄 Create Post (create_post) - JSONPlaceholder integration

1. 🧮 Calculate Tax (calculate_tax) - Tax calculations
2. 📧 Send Email (send_email) - Mock email sending
3. 🖼️ Image OCR (image_ocr) - Mock text extraction
4. 🗄️ Database Query (database_query) - Mock SQL queries

Load tools dynamically from external APIs alongside local tools.

const toolsManager = new MCPToolsManager({
  enabled: true,
  toolsUrl: 'http://localhost:3001/mcp/tools',
  timeout: 5000,
  retryAttempts: 2,
});

await toolsManager.initialize();

Your remote API should return:

{
  "tools": [
    {
      "name": "calculate_tax",
      "description": "Calculate tax for given amount",
      "executeUrl": "https://api.example.com/tools/calculate-tax",
      "method": "POST",
      "inputSchema": {
        "type": "object",
        "properties": {
          "amount": { "type": "number" },
          "rate": { "type": "number" }
        },
        "required": ["amount", "rate"]
      }
    }
  ]
}

export REMOTE_TOOLS_ENABLED=true              # Enable/disable remote tools
export REMOTE_TOOLS_URL=http://localhost:3001/mcp/tools
export REMOTE_TOOLS_TIMEOUT=5000
export REMOTE_TOOLS_RETRY_ATTEMPTS=2

Powerful web-based tool management interface for controlling tool availability:

• 🎛️ Tool Toggles: Enable/disable individual tools with visual switches
• 📊 Real-time Statistics: Live dashboard showing enabled/disabled counts
• ⚡ Bulk Operations: Enable All / Disable All tools at once
• 🔄 Auto-refresh: Automatically syncs with server every 30 seconds
• 🎨 Modern UI: Beautiful, responsive interface with visual feedback
• 💾 Persistent State: Tool configurations saved to tool-config.json

All tools are disabled by default - you must enable them via the admin panel.

1. Start server: npm run start:http
2. Open admin panel: http://localhost:3000/examples/admin.html
3. Toggle tools on/off as needed
4. Use client interface to test: http://localhost:3000/examples/client.html

The admin panel manages tool-config.json with this structure:

[
  {
    "toolName": "greg-test",
    "enabled": true
  },
  {
    "toolName": "http_post",
    "enabled": false
  }
]

The interactive web client dynamically loads and displays ONLY enabled tools:

• 🔍 Auto-Discovery: Loads enabled tools from server (local + remote)
• 🎯 Quick Tests: One-click testing for enabled tools
• 📊 Tool Statistics: Shows local vs remote breakdown
• ✅ Health Monitoring: Real-time server status
• 🔄 Dynamic Updates: Reflects tool availability in real-time

1. Start servers: npm run start:remote && npm run start:http
2. Enable tools in admin panel: http://localhost:3000/examples/admin.html
3. Use client interface: http://localhost:3000/examples/client.html
4. Click "Load Available Tools" to see enabled tools
5. Use quick test buttons or detailed tool information

npm run start:http      # Local tools only
# OR with remote tools:
npm run start:remote    # Terminal 1: Remote tools server
npm run start:http      # Terminal 2: HTTP server (8 tools total)

npm run build
node dist/index.js

Then add to your MCP configuration:

{
  "mcpServers": {
    "demo-tools": {
      "command": "node",
      "args": ["path/to/mcp-server-remote-architecture/dist/index.js"]
    }
  }
}

Important for Cursor/Claude:

• All tools are disabled by default - you'll see 0 tools initially
• Enable tools first: Use the admin panel to enable desired tools
  1. Run: npm run start:http
  2. Open: http://localhost:3000/examples/admin.html
  3. Enable tools you want to use
  4. Restart Cursor's MCP connection to see tools
• Tool state persists across server restarts

The server provides dedicated admin endpoints for tool management:

Get all tool configurations (enabled and disabled):

{
  "success": true,
  "tools": [
    {
      "toolName": "greg-test",
      "enabled": true,
      "type": "local",
      "description": "amazing tool"
    }
  ],
  "count": 4
}

Toggle a tool's enabled/disabled state:

curl -X POST http://localhost:3000/admin/tools/greg-test/toggle \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Response:

{
  "success": true,
  "message": "Tool 'greg-test' enabled",
  "toolName": "greg-test",
  "enabled": true,
  "timestamp": "2025-06-21T18:29:38.323Z"
}

Problem: MCP server shows red dot and 0 tools in Cursor Solution:

1. Tools are disabled by default - enable them via admin panel
2. Ensure tool configuration file exists in project directory
3. Restart Cursor's MCP connection after enabling tools

Problem: Server creates new config with all tools disabled Solution: Tool config uses absolute paths - works regardless of working directory

# Test tool endpoints
curl http://localhost:3000/mcp/tools          # Enabled tools only
curl http://localhost:3000/mcp/tools/local    # Enabled local tools only
curl http://localhost:3000/mcp/tools/remote   # Enabled remote tools only

# Test admin endpoints
curl http://localhost:3000/admin/tools         # All tool configurations
curl -X POST http://localhost:3000/admin/tools/greg-test/toggle \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'                       # Enable a tool

# Test specific tools (only if enabled)
curl http://localhost:3000/mcp/test/greg-test
curl http://localhost:3000/mcp/test/calculate_tax  # Remote tool

# Note: Tools must be enabled first via admin panel
curl -X POST http://localhost:3000/mcp/call-tool \
  -H "Content-Type: application/json" \
  -d '{"tool": "calculate_tax", "parameters": {"amount": 100, "rate": 0.08}}'

1. Create src/tools/my-tool.ts
2. Export from src/tools/index.ts
3. Restart server to load new tool
4. Enable the tool via admin panel (disabled by default)

1. Add tool definition to your remote API
2. Implement the execution endpoint
3. Refresh remote tools or restart server
4. Enable the tool via admin panel (disabled by default)

• All new tools are disabled by default
• Use the admin panel to enable/disable tools
• Tool states persist in tool-config.json
• Only enabled tools appear in /mcp/tools endpoints

MIT License - see LICENSE file for details.