RAG Glossary - MCP Server

Model Context Protocol (MCP) server providing glossary search and management tools for AI assistants.

MCP Server Architecture

src/server.ts implements the Model Context Protocol server with tool handlers.

Tool Handler Pattern

Each MCP tool has a dedicated async handler function:

• handleSearchTerm(args, startTime) → CallToolResult
• handleSemanticSearch(args, startTime) → CallToolResult

The main request handler validates input and dispatches to handlers using a handler registry pattern.

Timeout Constants

All Python backend communication uses named timeout constants:

• TIMEOUT_EXACT_SEARCH - 10 seconds for exact term lookups
• TIMEOUT_SEMANTIC_SEARCH - 15 seconds for semantic searches

Error Handling

All errors are caught, logged to stderr, and returned as structured MCP error responses with isError: true.

Development

Setup

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

Testing

# Run all tests
npm test

# Run specific test
npm test -- tests/server-integration.test.ts

# Watch mode
npm test -- --watch

Linting

# Run linter
npm run lint

# Fix auto-fixable issues
npm run lint -- --fix

Usage

The MCP server provides tools for AI assistants to search and manage glossaries:

Tools

• search_term - Find exact term match with definition

  • Required: term
  • Optional: workspace_root (enables multi-glossary search), include_global (default: true)
  • Returns definition with source glossary attribution in multi-glossary mode

• semantic_search - Find related terms by semantic similarity

  • Required: query
  • Optional: limit (default: 5), workspace_root (enables multi-glossary search), include_global (default: true)
  • Returns merged results from all glossaries with source attribution in multi-glossary mode

• rebuild_glossary - Rebuild glossary database from data files

  • Required: glossary_name (or "all")
  • Optional: workspace_root

Multi-Glossary Query Support

When workspace_root parameter is provided, the MCP server operates in multi-glossary mode:

Features:

• Searches across all glossaries in the workspace (local + global)
• Merges results by relevance score for semantic searches
• Includes source glossary attribution in results: _(from glossary-name)_
• Deduplicates terms appearing in multiple glossaries (keeps highest scoring version)
• Configurable global glossary inclusion via include_global parameter

Usage Example:

// Exact search across all glossaries
await client.callTool("search_term", {
  term: "Academic Bank of Credits",
  workspace_root: "/path/to/workspace"
});

// Semantic search with merged results
await client.callTool("semantic_search", {
  query: "credit transfer",
  limit: 5,
  workspace_root: "/path/to/workspace",
  include_global: true
});

Result Format: Results include source glossary attribution:

• Exact search: **Term** _(from glossary-name)_
• Semantic search: **Term** _(glossary-name)_ (score: 0.850)

Troubleshooting

Tools Not Appearing in VS Code

Symptom: MCP tools don't register or fail silently

Primary Cause: STDIO protocol corruption

🚨 CRITICAL: Never use console.log() in MCP server code. This corrupts the JSON-RPC protocol on stdout.

// ❌ BAD - corrupts MCP protocol
console.log("Debug message");
console.log(result);

// ✅ GOOD - logs to stderr
console.error("Debug message");
console.error("Result:", result);

Audit code for stdout pollution:

grep -r "console\.log" src/
# Should return nothing in production code (tests are OK)

Test with MCP Inspector

⚠️ Known Issue: MCP Inspector may freeze on first connection if glossary databases aren't initialised or if there are Python environment issues.

Quick test without Inspector (lightweight):

# Test server starts without errors
$env:RAG_GLOSSARY_BACKEND="c:\path\to\python-backend"
$env:RAG_GLOSSARY_GLOBAL="c:\path\to\glossaries"
node dist\server.js 2>&1 | Select-Object -First 10
# Ctrl+C to stop - if you see no errors in first few lines, server is OK

Interactive UI testing:

npx @modelcontextprotocol/inspector node dist/server.js
# Opens browser at http://localhost:6274
# May take 30-60 seconds on first run while databases initialize

CLI testing (for automation):

# List available tools (may timeout on first run)
npx @modelcontextprotocol/inspector --cli node dist/server.js --method tools/list

# Test exact search
npx @modelcontextprotocol/inspector --cli node dist/server.js \
  --method tools/call \
  --tool-name search_term \
  --tool-arg term="Academic Bank of Credits"

# Test semantic search
npx @modelcontextprotocol/inspector --cli node dist/server.js \
  --method tools/call \
  --tool-name semantic_search \
  --tool-arg query="credit transfer" \
  --tool-arg limit=5

If Inspector freezes:

1. Pre-initialize databases (recommended):

   cd python-backend
   .\venv\Scripts\Activate.ps1
   python -m src.integration --glossary all --cleanup

2. Use fast fallback mode (YAML-only, no vector search):

   $env:RAG_GLOSSARY_FAST_FALLBACK="true"
   npx @modelcontextprotocol/inspector --cli node dist/server.js --method tools/list

3. Check Python environment:

   cd python-backend
   .\venv\Scripts\python.exe -c "import chromadb; print('OK')"

Python Backend Communication

Test Python backend independently:

cd ../python-backend
.\venv\Scripts\Activate.ps1

# Test JSON RPC protocol
echo '{"action":"exact_search","term":"test"}' | python -m src.mcp_bridge

# Should output ONLY JSON response (no debug text)

Common Python backend issues:

• ❌ print() statements in mcp_bridge.py (except final response)
• ❌ Missing dependencies: pip install -r requirements.txt
• ❌ ChromaDB not initialised: Run integration script first
• ❌ Wrong Python version: Requires Python 3.11+

Configuration Issues

Verify .vscode/mcp.json paths:

{
  "mcpServers": {
    "rag-glossary": {
      "command": "node",
      "args": [
        "C:\\Users\\...\\mcp\\rag-glossary-server\\dist\\server.js"
      ],
      "env": {
        "RAG_GLOSSARY_BACKEND": "C:\\Users\\...\\python-backend",
        "RAG_GLOSSARY_GLOBAL": "C:\\Users\\...\\glossaries"
      }
    }
  }
}

Path requirements:

• ✅ Use absolute paths (not relative)
• ✅ Ensure dist/server.js exists (run npm run build)
• ✅ Ensure Python backend path contains src/mcp_bridge.py
• ✅ Ensure glossaries path exists

Timeout Errors

Symptoms:

• "Request timeout after 10000ms"
• "Python backend not responding"

Solutions:

1. Check Python environment:

   cd python-backend
   .\venv\Scripts\Activate.ps1
   python -c "import chromadb; print('OK')"

2. Increase timeout (if needed for large glossaries):

   // src/server.ts
   const TIMEOUT_SEMANTIC_SEARCH = 30000; // 30 seconds

3. Check glossary staleness:

   # Rebuild glossaries
   cd python-backend
   python -m src.integration --glossary all --cleanup

Debugging Logs

View server stderr output:

# Run server manually to see logs
node dist/server.js 2> server-debug.log

# In another terminal, interact via Inspector
npx @modelcontextprotocol/inspector --cli node dist/server.js --method tools/list

# Check logs
cat server-debug.log

Log patterns to look for:

• [MCP] prefix indicates MCP server logs
• Spawning Python backend: shows backend startup
• Python backend response: shows communication
• Error: indicates failures

Common Error Messages

| Error | Cause | Solution | |-------|-------|----------| | "Invalid JSON-RPC" | stdout pollution | Remove console.log() | | "ENOENT" | File not found | Check paths in config | | "spawn python ENOENT" | Python not in PATH | Use absolute Python path | | "Glossary not found" | Wrong glossary name | Check glossary-config.yaml | | "ChromaDB error" | Database corruption | Rebuild with --cleanup |

Validation Checklist

✅ Before reporting issues:

1. ☑️ Build succeeds: npm run build
2. ☑️ Tests pass: npm test
3. ☑️ No stdout logs: grep "console.log" src/server.ts empty
4. ☑️ Inspector shows tools: npx @modelcontextprotocol/inspector --cli ...
5. ☑️ Python backend works: echo '{...}' | python -m src.mcp_bridge
6. ☑️ Config paths absolute: Check .vscode/mcp.json
7. ☑️ Glossaries compiled: Check .chroma_db/ exists

Additional Resources

• MCP Debugging Guide
• MCP Inspector Docs
• Python Backend README