npm package: @randalliser/rag-glossary-server
Description: MCP server for glossary RAG system
Author: Randalliser
Latest version: 1.0.0

# 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

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch
```

### Testing

```bash
# Run all tests
npm test

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

# Watch mode
npm test -- --watch
```

### Linting

```bash
# 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:**

```javascript
// 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.

```typescript
// ❌ 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**:

```bash
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):

```powershell
# 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**:

```bash
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):

```bash
# 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):

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

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

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

3. **Check Python environment**:

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

### Python Backend Communication

**Test Python backend independently**:

```powershell
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**:

```json
{
  "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**:

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

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

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

3. **Check glossary staleness**:

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

### Debugging Logs

**View server stderr output**:

```powershell
# 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](https://modelcontextprotocol.io/docs/tools/debugging)
- [MCP Inspector Docs](https://github.com/modelcontextprotocol/inspector)
- [Python Backend README](../../python-backend/README.md)