YellowPages

Discover and execute API operations. Your agent stays in control.

YellowPages is an MCP (Model Context Protocol) server that exposes two tools: discover (RAG over an OpenAPI schema, returns matching operations with their schema) and execute (runs an operation by ID with given params). No LLM inside the server—your caller agent chooses which operation and parameters to use.

---

Why it exists

APIs are everywhere, but using them usually means reading specs, copying URLs, and wiring parameters. YellowPages inverts that: you load an OpenAPI schema once and index it, then your MCP host (e.g. Cursor) can call discover with a natural-language query to get matching operations (with IDs and JSON schema), then call execute with the chosen operation and params. The server does RAG for discovery and runs the HTTP call; the caller agent decides what to call and with what arguments.

---

How it works

There are two applications:

1. Indexer – Build the vector DB once (or when the schema changes). Run uv run python -m src.indexer with your OpenAPI schema path and Chroma directory (env or --schema-path / --chroma-dir). This flattens the schema into operations and indexes them in Chroma with local embeddings (sentence-transformers/all-MiniLM-L6-v2 by default).
2. MCP server – Run uv run main.py to start the server. It loads the existing Chroma index and schema (the indexer must have been run first). The server exposes two tools: discover_operations (RAG only; returns matching operations with ID and schema) and execute_operation (runs an operation by name with path/query/body params). No LLM inside the server; the caller agent chooses what to execute.

So: build the index once; then the caller uses discover then execute. The server expects the Chroma directory to already exist.

---

Quick start

UV is the recommended package manager. From the project root:

uv sync
# Build the vector index from your OpenAPI schema (once, or when schema changes)
uv run python -m src.indexer
# Start the MCP server (no API key needed; uses local embeddings)
uv run main.py

Or run the server as uv run python -m src.mcp.server (same effect). The server uses stdio by default so hosts like Cursor can launch it as a subprocess. For remote use, set YELLOW_PAGES_TRANSPORT=streamable-http and run uv run main.py.

Without UV: pip install -e ., then run the indexer once (python -m src.indexer), then python main.py (or python -m src.mcp.server).

---

Environment variables

Variable	Description
YELLOW_PAGES_SCHEMA_PATH	OpenAPI schema file (JSON or YAML). Default: ./sample_schema.json
YELLOW_PAGES_CHROMA_DIR	Chroma vector DB directory. Default: ./chroma_db_agent_tools_v9. If you switch embedding models, remove this directory (or use a new path) so the next indexer run re-indexes.
YELLOW_PAGES_EMBEDDING_MODEL	HuggingFace/sentence-transformers model name. Default: sentence-transformers/all-MiniLM-L6-v2
YELLOW_PAGES_TRANSPORT	stdio (default) or streamable-http. Only when running the server directly.

---

Adding to Cursor

In your MCP settings, add a server entry for YellowPages (UV recommended):

{
  "mcpServers": {
    "yellow-pages": {
      "command": "uv",
      "args": ["run", "/path/to/yellow-pages/main.py"]
    }
  }
}

Without UV: "command": "python", "args": ["/path/to/yellow-pages/main.py"].

Use discover_operations with a natural-language query to get matching API operations (with name, method, url, parameters), then use execute_operation with the chosen operation name and params. No API key required for the MCP server.

---

Schema format

The server expects a standard OpenAPI 3.x file with a servers block. It converts each operation into a simplified shape: name, tags, url, method, parameters, responses. The bundled sample_schema.json (Nager.Date holiday API) is there so you can try it immediately.

---

Website deployment

The repository now includes a Vite + React website in website/ and a GitHub Actions workflow that publishes the built app to GitHub Pages from the main branch.

Branch and path conventions:

• main is the deploy branch.
• The website source lives under website/.
• The published site root is the build output in website/dist/.
• When adding pages or routes, keep them under website/src/ and prefer route-based navigation over hard-coded file paths.