Use when adding, removing, or troubleshooting upstream sources for the mcp-semantic-gateway — native MCP servers, OpenAPI / Swagger specs, or hand-authored skill libraries. Covers `~/.mcp_semantic_gateway/config.toml` syntax, auth wiring, and the `index` rebuild loop.
Use when the mcp-semantic-gateway is connected and the agent needs to find the right tool or workflow for a user request — refunding an order, onboarding a record, triaging an issue, etc. Establishes the search-before-guess pattern. Trigger on any task where the obvious tool name is not already in the agent's context.
Use when the user is setting up the mcp-semantic-gateway for the first time, asks how to install or initialize it, or wants to point a coding agent (Claude Desktop, Claude Code, Cursor, Codex, opencode, pi) at the gateway. Covers `init`, the data directory layout, and the MCP client connection block.
Use when the user wants to generate `SKILL.md` workflows from an OpenAPI / Swagger source via the mcp-semantic-gateway `synth` command, inspect the synth cache, debug rejections, or register the generated library so an agent can find it. Triggers on words like "synth", "generate skills", "skill synthesis", "use cases".
Use when adding a new upstream source type to mcp-semantic-gateway (alongside the existing `mcp`, `openapi`, and `skill` types) — e.g., GraphQL, gRPC reflection, a proprietary catalog API. Walks the config model, ingestion collector, registry surface, and router branches that need to be extended.
Use when contributing to the mcp-semantic-gateway repository — cloning, installing dev dependencies with uv, navigating the source tree, or running the Makefile targets. Triggers on tasks about local development environment for this codebase.
Use when cutting a new release of mcp-semantic-gateway — bumping the version in pyproject.toml, building the wheel, publishing to PyPI, or troubleshooting the publish step. Triggers on "release", "publish", "bump version", "new version", "PyPI".
Use when running, debugging, or extending the test suite for the mcp-semantic-gateway repository. Covers pytest invocation, the e2e harness, fixtures, the stub LLM, and how unit tests are organized per pipeline stage.