Skip to content

TESTING.md

Latest commit

 

History

History
176 lines (127 loc) · 4.57 KB

TESTING.md

File metadata and controls

176 lines (127 loc) · 4.57 KB

Testing Guide

This guide covers three ways to test your OpenContext server locally.

Prerequisites

Before testing:

  1. Create config.yaml from config-example.yaml and enable exactly one plugin
  2. Install dependencies: pip install aiohttp
  3. Start the server: python3 scripts/local_server.py

The server runs at http://localhost:8000/mcp. Keep it running while you test.

Method 1: Terminal (cURL)

Use the terminal to send requests directly to the server.

Ping:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

List tools:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Call a tool:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ckan__search_datasets","arguments":{"query":"housing","limit":3}}}'

For a full test (initialize, list tools, call tool), run:

./scripts/test_streamable_http.sh

Method 2: Claude (Connectors)

  1. Connect via Claude Connectors (see Getting Started)
  2. Add a custom connector with URL: http://localhost:8000/mcp
  3. Enable the connector in your conversation (click "+" → Connectors → toggle on)
  4. Ask Claude to search your data or list available tools

Note: Localhost only works with Claude Desktop. For Claude.ai (web), use MCP Inspector or deploy first.

Method 3: MCP Inspector

MCP Inspector is a web-based tool for testing MCP servers.

  1. With the server running, open a new terminal
  2. Run: npx @modelcontextprotocol/inspector
  3. The Inspector UI opens in your browser (typically http://localhost:6274)
  4. In the Inspector, select streamable-http as the transport
  5. Enter the URL: http://localhost:8000/mcp
  6. Use the Tools tab to list and call tools

Method 4: Claude Desktop / Claude Code via stdio_bridge.py

Claude Desktop and Claude Code speak MCP over stdio, not HTTP. stdio_bridge.py is a small Python adapter that reads JSON-RPC from stdin, forwards it to the local HTTP server, and writes responses back to stdout — a dependency-free replacement for the Go client in client/ for cases where you just want a local stdio connection.

Start the local server first (python local_server.py from the repo root — this entry point accepts both / and /mcp), then register the bridge as an MCP server.

Claude Desktop — edit claude_desktop_config.json:

{
  "mcpServers": {
    "boston-opendata": {
      "command": "python",
      "args": [
        "C:/projects/boston/OpenContext/stdio_bridge.py",
        "http://localhost:8000/mcp"
      ]
    }
  }
}

Claude Code — add an .mcp.json at the project root (or under .claude/):

{
  "mcpServers": {
    "boston-opendata": {
      "command": "python",
      "args": [
        "C:/projects/boston/OpenContext/stdio_bridge.py",
        "http://localhost:8000/mcp"
      ]
    }
  }
}

The URL argument is optional — it defaults to http://localhost:8000/mcp. Pass a different URL to point at a deployed endpoint instead of the local server.

Adjust the interpreter path (e.g. C:/projects/boston/OpenContext/venv/Scripts/python.exe) if you want to pin to a specific virtualenv. stdio_bridge.py uses only Python stdlib, so no extra installs are required.

Quick Checks

Optional checks before starting the server.

Config validation:

python3 -c "
import yaml
from core.validators import load_and_validate_config
config = load_and_validate_config('config.yaml')
print('Config valid:', config['server_name'])
"

Plugin loading:

python3 -c "
import asyncio, yaml
from core.plugin_manager import PluginManager
async def t():
    with open('config.yaml') as f: config = yaml.safe_load(f)
    pm = PluginManager(config)
    await pm.load_plugins()
    print('Tools:', [t['name'] for t in pm.get_all_tools()])
    await pm.shutdown()
asyncio.run(t())
"

Unit Tests

pip install pytest pytest-asyncio sqlparse
pytest
pytest tests/test_plugin_manager.py -v
pytest --cov=core --cov=plugins

Testing Against Production

To test a deployed server, use the Lambda URL or API Gateway URL:

LAMBDA_URL="https://your-lambda-url.lambda-url.us-east-1.on.aws"
curl -X POST $LAMBDA_URL/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

See Deployment for how to get the URL.