toad-mcp-server

🔌 MCP server exposing portfolio AI tools via Model Context Protocol. Connect to Claude Desktop and call Semantic Search, Eval Framework, and Prompt Management tools directly from chat.

🏗️ Architecture

┌─────────────────────┐    stdio / HTTP     ┌──────────────────────────┐
│   Claude Desktop    │◄────────────────-──►│    toad-mcp-server       │
│   (MCP Client)      │                     │                          │
└─────────────────────┘                     │  ┌────────────────────┐  │
                                            │  │ toad_search_docs   │──┼──► Semantic Search API
                                            │  ├────────────────────┤  │
                                            │  │ toad_run_eval      │──┼──► Eval Framework API
                                            │  ├────────────────────┤  │
                                            │  │ toad_system_status │──┼──► Health checks
                                            │  ├───────────────-────┤  │
                                            │  │ toad_list_prompts  │  │
                                            │  ├────────────────────┤  │
                                            │  │ toad_get_prompt    │  │
                                            │  └────────────────────┘  │
                                            └──────────────────────────┘

🛠️ Tools

Tool	Description	Read-only
toad_search_documents	Semantic search over documents via natural language query	Yes
toad_run_eval	Run eval suite against a prompt variant, returns scores	No
toad_system_status	Health check all portfolio services (latency, status)	Yes
toad_list_prompts	List prompts with pagination and tag filtering	Yes
toad_get_prompt	Get prompt by name with version, template, score history	Yes

All tools support response_format: "markdown" | "json" where applicable.

📦 Resources

URI	Description
toad://system/status	Health status of all services (JSON)
toad://prompts/{name}	Get prompt by name with full metadata (JSON)

🚀 Quick Start

# Install
npm install

# Build
npm run build

# Run (stdio — for Claude Desktop)
npm start

# Run (HTTP — for remote/multi-client access)
TRANSPORT=http npm start

# Dev mode
npm run dev

🖥️ Claude Desktop Setup

1. Build the server:

   npm run build

2. Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "toad-mcp-server": {
         "command": "node",
         "args": ["dist/index.js"],
         "cwd": "/absolute/path/to/toad-mcp-server",
         "env": {
           "SEMANTIC_SEARCH_URL": "http://localhost:3001",
           "EVAL_FRAMEWORK_URL": "http://localhost:3002"
         }
       }
     }
   }

3. Restart Claude Desktop — tools appear automatically.

🔍 Testing with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Opens a web UI to test each tool interactively.

⚙️ Environment Variables

Variable	Default	Description
SEMANTIC_SEARCH_URL	http://localhost:3001	Semantic Search Engine endpoint
EVAL_FRAMEWORK_URL	http://localhost:3002	Eval Framework endpoint
TRANSPORT	stdio	Transport mode: stdio or http
PORT	3100	HTTP transport port
HOST	127.0.0.1	HTTP transport bind address

📜 Scripts

Script	Description
npm run build	Compile TypeScript to dist/
npm run dev	Run with tsx (hot reload)
npm start	Run compiled server
npm run lint	ESLint check
npm run format	Prettier format

🧱 Tech Stack

• TypeScript (NodeNext, strict)
• @modelcontextprotocol/sdk — MCP server SDK
• Zod v4 — input validation
• ESLint + Prettier + Husky — code quality
• GitHub Actions — CI (lint → format → build)

📄 License

ISC