Merge pull request #3 from gregra81/support_remote_tools

support loading remote tools

Author: gregra81

README.md

@@ -1,15 +1,15 @@
 # MCP Tools Demo
 
-A **Model Context Protocol (MCP)** implementation showcasing clean, modular tool architecture with multiple server options and an interactive browser client.
+A **Model Context Protocol (MCP)** implementation showcasing clean, modular tool architecture with **local and remote tools** support and an interactive browser client.
 
 ## 🌟 Features
 
 - **🏗️ Clean Architecture**: Modular tool design with `MCPToolsManager`
-- **🔧 4 Demo Tools**: HTTP POST, Weather API, Create Post, and Greg Test tools
-- **🌐 Browser Client**: Interactive web interface for testing tools
-- **📡 Multiple Server Options**: Stdio and Simple HTTP
-- **🧪 Comprehensive Testing**: Automated test suites and manual testing options
-- **🔒 Type Safety**: Full TypeScript implementation with proper validation
+- **🔧 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
+- **📡 Multiple Server Options**: Stdio, Simple HTTP, and Remote Tools servers
+- **🔒 Type Safety**: Full TypeScript implementation with Zod validation
 
 ## 🚀 Quick Start
 
@@ -21,124 +21,212 @@ cd mcp-hello-world
 npm install
 ```
 
-### 2. Browser Demo (Recommended)
+### 2. Full Demo (Local + Remote Tools)
 
-Start the HTTP server and open the browser client:
+Start both servers for the complete experience:
 
 ```bash
+# 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: **http://localhost:3000/examples/client.html**
 
-### 3. Command Line Usage
+### 3. Local Tools Only
+
+```bash
+# Just local tools (4 tools)
+REMOTE_TOOLS_ENABLED=false npm run start:http
+```
+
+### 4. Command Line Usage (Cursor/Claude)
 
 ```bash
-# Build the project
 npm run build
+node dist/index.js  # Stdio MCP server
+```
 
-# Test tools directly
-node dist/index.js  # Stdio MCP server (for Cursor/Claude)
+## 🏗️ Architecture
+
+### Modular Structure
+
+```
+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
+│   ├── 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
+│   ├── remote-tools-api-example.json      # Remote tools definition
+│   └── remote-tool-server-example.js     # 🌐 Remote tools server
+└── dist/                       # Compiled JavaScript
 ```
 
-## Key Design Principles
+### Key Design Principles
 
-- **Single Source of Truth**: All tools defined in `src/tools/` directory
+- **Single Source of Truth**: Local tools in `src/tools/`, remote tools via API
 - **Generic Manager**: `MCPToolsManager` automatically loads all tools
-- **Modular Tools**: Each tool is self-contained with handler and schema
-- **Multiple Interfaces**: Same tools work with stdio, HTTP, SSE, and streaming
+- **Hot-loadable**: Remote tools can be added/updated without restart
+- **Multiple Interfaces**: Same tools work with stdio, HTTP, and browser
 
 ## 🔧 Available Tools
 
-### 1. 🎭 Greg Test Tool (`greg-test`)
-Your amazing mood testing tool!
+### 🏠 Local Tools (4)
+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
 
-**Parameters**:
-- `feeling` (string, required): Your current mood
+### 🌐 Remote Tools (4)
+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
 
-**Example**:
-```json
-{
-  "tool": "greg-test",
-  "parameters": {
-    "feeling": "excited about the new architecture"
-  }
-}
-```
+## 🌐 Remote Tools Support
 
-### 2. 🌐 HTTP POST Tool (`http_post`)
-Make HTTP POST requests to any API.
+Load tools dynamically from external APIs alongside local tools.
 
-**Parameters**:
-- `url` (string, required): Target URL
-- `data` (object, required): JSON data to send
-- `headers` (object, optional): Additional headers
-- `timeout` (number, optional): Request timeout in ms
+### Quick Configuration
 
-### 3. 🌤️ Weather Tool (`get_weather`)
-Get weather information using OpenWeatherMap API (or mock data).
+```typescript
+const toolsManager = new MCPToolsManager({
+  enabled: true,
+  toolsUrl: 'http://localhost:3001/mcp/tools',
+  timeout: 5000,
+  retryAttempts: 2,
+});
 
-**Parameters**:
-- `city` (string, required): City name
-- `apiKey` (string, optional): OpenWeatherMap API key
-- `units` (string, optional): Temperature units (metric/imperial/kelvin)
+await toolsManager.initialize();
+```
 
-### 4. 📄 Create Post Tool (`create_post`)
-Create posts using JSONPlaceholder API.
+### Remote Tools API Format
 
-**Parameters**:
-- `title` (string, required): Post title
-- `body` (string, required): Post content
-- `userId` (number, optional): User ID
+Your remote API should return:
+
+```json
+{
+  "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"]
+      }
+    }
+  ]
+}
+```
+
+### Environment Configuration
+
+```bash
+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
+```
 
 ## 🌐 Browser Client
 
-The interactive web client provides a beautiful interface for testing all tools:
+The interactive web client dynamically loads and displays **ALL available tools**:
 
 ### Features
-- **🔍 Auto-Discovery**: Automatically loads all available tools
-- **🎯 Quick Tests**: One-click testing with default parameters
-- **📋 Individual Forms**: Detailed input forms for each tool
-- **📊 Real-time Logging**: Activity log with timestamps
-- **✅ Health Monitoring**: Server connection status
+- **🔍 Auto-Discovery**: Loads all tools from server (local + remote)
+- **🎯 Quick Tests**: One-click testing for all 8 tools
+- **📊 Tool Statistics**: Shows local vs remote breakdown
+- **✅ Health Monitoring**: Real-time server status
+- **🔄 Dynamic Updates**: Reflects tool availability in real-time
 
 ### Usage
-1. Start the HTTP server: `npm run start:http`
+1. Start servers: `npm run start:remote && npm run start:http`
 2. Open: http://localhost:3000/examples/client.html
-3. Click "Check Server Health" to connect
-4. Use "Load Available Tools" to see all tools
-5. Test tools with quick buttons or detailed forms
+3. Click "Load Available Tools" to see all 8 tools
+4. Use quick test buttons or detailed tool information
 
 ## 🚀 Running the Servers
 
-### 1. HTTP Server (Browser Demo)
+### HTTP Server (Browser Demo)
 ```bash
-npm run start:http      # Production build + start
+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)
 ```
-**URL**: http://localhost:3000
 
-### 2. Stdio Server (Cursor/Claude Integration)
+### Stdio Server (Cursor/Claude Integration)
 ```bash
 npm run build
+node dist/index.js
 ```
 
-Then in your mcp servers setup add the following:
-
-```
+Then add to your MCP configuration:
+```json
 {
   "mcpServers": {
-    "demo-mcp": {
-        "command": "node",
-        "args": [
-            "~/Development/dead-simple-mcp-server/dist/index.js"
-        ]
-      }
+    "demo-tools": {
+      "command": "node",
+      "args": ["path/to/dead-simple-mcp-server/dist/index.js"]
     }
+  }
 }
+```
+
+## 🧪 Testing
+
+### Quick API Tests
+```bash
+# Test tool endpoints
+curl http://localhost:3000/mcp/tools          # All tools
+curl http://localhost:3000/mcp/tools/local    # Local tools only  
+curl http://localhost:3000/mcp/tools/remote   # Remote tools only
+
+# Test specific tools
+curl http://localhost:3000/mcp/test/greg-test
+curl http://localhost:3000/mcp/test/calculate_tax  # Remote tool
+```
 
+### Tool Calls
+```bash
+curl -X POST http://localhost:3000/mcp/call-tool \
+  -H "Content-Type: application/json" \
+  -d '{"tool": "calculate_tax", "parameters": {"amount": 100, "rate": 0.08}}'
 ```
 
+## 🔧 Adding New Tools
+
+### Local Tools
+1. Create `src/tools/my-tool.ts`
+2. Export from `src/tools/index.ts`
+3. Done! Auto-loaded everywhere.
+
+### Remote Tools
+1. Add tool definition to your remote API
+2. Implement the execution endpoint
+3. Tools appear automatically when server loads
+
 ## 📄 License
 
 MIT License - see LICENSE file for details.
 
+---
+
+**🎉 Enjoy your dynamic, distributed MCP tools architecture!**