Server Suite

Five production-ready Model Context Protocol (MCP) servers built with the official Python SDK. Supports both stdio and HTTP/SSE transports.

This suite enables any MCP-compatible client (Claude Desktop, Cursor, OpenCode) to interact with restaurant data, web search, browser automation, and filesystem operations.

---

What is MCP?

MCP is an open standard that lets AI applications connect to external tools and data sources through a uniform interface. Think of it as USB-C for AI tools — write once, integrate everywhere.

---

Servers

1. restaurant_server (stdio)

Wraps restaurant ordering tools for MCP clients.

Tools: get_menu, check_dish_availability, check_quantity, add_item_to_cart, view_cart, get_suggestions, finalize_order

2. searxng_server (stdio)

Wraps a local SearXNG meta-search engine.

Tools: web_search, image_search

• Supports categories, language, safesearch, time range, and result count
• Uses httpx.AsyncClient for non-blocking requests

3. pinchtab_server (stdio)

Wraps a local PinchTab headless browser.

Tools: navigate, snapshot, click, fill, extract_text

• Enables LLM-driven web browsing and form interaction
• Communicates via PinchTab's REST API

4. filesystem_server (stdio)

Sandboxed filesystem operations with path traversal protection.

Tools: read_file, write_file, list_directory, search_files, file_stat, move_file, copy_file, delete_file

• _resolve() enforces workspace sandboxing via Path.relative_to()
• Binary files returned as base64

5. filesystem_server_sse (HTTP/SSE)

The same filesystem server exposed over Server-Sent Events on HTTP.

• Built with Starlette + uvicorn + anyio memory streams
• Per-session JSON-RPC message routing
• Endpoints: / (info), /sse (event stream), /messages (POST)

---

Quick Start

1. Install

pip install -r requirements.txt

2. Configure MCP Client

Copy mcp.json.example to your client's config directory and update URLs:

cp mcp.json.example ~/.config/claude/mcp.json   # Claude Desktop
cp mcp.json.example ~/.config/opencode/mcp.json # OpenCode

3. Run Individual Servers

# stdio servers (spawned by MCP client)
python -m mcp_servers.restaurant_server
python -m mcp_servers.searxng_server
python -m mcp_servers.pinchtab_server
python -m mcp_servers.filesystem_server /path/to/workspace

# SSE server (runs as HTTP daemon)
python -m mcp_servers.filesystem_server_sse /path/to/workspace
# Then connect to http://localhost:3000/sse

---

SSE Transport Deep Dive

The SSE server is the most technically interesting component:

# Per-session memory streams
rx_send, rx_recv = anyio.create_memory_object_stream(100)
tx_send, tx_recv = anyio.create_memory_object_stream(100)

# MCP server runs in background asyncio task
await server.run(rx_recv, tx_send, server.create_initialization_options())

# SSE handler serializes messages as JSON events
yield f"event: message\ndata: {message.model_dump_json()}\n\n"

# Client POSTs to /messages, injected into receive stream
await SESSIONS[session_id]["rx_send"].send(JSONRPCMessage.model_validate(data))

Key design decisions:

• Memory streams decouple HTTP I/O from MCP protocol logic
• Session cleanup on disconnect prevents resource leaks
• JSON-RPC message validation ensures protocol compliance

---

Environment Variables

Variable	Default	Description
SEARXNG_URL	http://localhost:8080	SearXNG base URL
PINCHTAB_URL	http://localhost:9867	PinchTab API URL
RESEARCH_WORKSPACE	~/workspace/research	Research report output directory
MCP_HOST	0.0.0.0	SSE server bind host
MCP_PORT	3000	SSE server bind port

---

Architecture

MCP Client (Claude Desktop / Cursor / OpenCode)
        |
        v
+-- stdio transport --+     +-- SSE transport --+
|  python -m server  |     |  http://host:3000 |
+--------------------+     +-------------------+
        |                           |
        v                           v
  Restaurant Data            Filesystem Ops
  SearXNG Search             (remote access)
  PinchTab Browser

---

Security Notes

• Filesystem sandboxing: _resolve() prevents path traversal above workspace root
• stdio transport: No open network ports — most secure option
• SSE transport: Bind to 127.0.0.1 or use reverse proxy with TLS for remote access
• PinchTab IDPI: Restricts browsing to allowed origins by default

---

Testing

Each server can be tested manually:

# Test SearXNG MCP server
python -m mcp_servers.searxng_server
# Then send JSON-RPC messages via stdin

# Test filesystem SSE server
curl http://localhost:3000/
curl http://localhost:3000/sse

---

Tech Stack

Component	Technology
MCP Framework	mcp Python SDK
HTTP Client	httpx (async)
SSE Server	starlette + uvicorn + anyio
Data Format	JSON / JSON-RPC

---

License

MIT