메뉴
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.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
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 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".
| name | mcp-gateway-dev-setup |
| description | 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. |
This is a uv-managed Python 3.12+ package using the uv_build backend.
git clone https://github.com/codeninja/mcp-semantic-gateway && cd mcp-semantic-gateway
uv sync # runtime deps only
uv sync --dev # also install dev tools (pytest, ruff, mkdocs)
The console entry point mcp-semantic-gateway is registered against mcp_semantic_gateway.cli.main:app. Run it via uv run mcp-semantic-gateway ... during development to use the in-tree code.
src/mcp_semantic_gateway/
├── cli/ # typer app — `main.py`, `synth.py`, `onboard.py`
├── config/ # pydantic models + `loader.py` for config.toml
├── ingestion/ # collectors and the index-builder pipeline
├── integration/ # MCP proxy, HTTP server, OpenAPI executor, router
├── llm/ # provider abstractions (Anthropic + OpenAI-compat)
├── retrieval/ # SearchCore, ToolRegistry, embedding store
├── storage/ # data dir initialization, on-disk layout
└── skills/ # bundled skills shipped to onboard targets
Tests live under tests/, fixtures under tests/fixtures/. The end-to-end suite (test_e2e.py) spins up a real proxy against stub upstreams.
| Target | Action |
|---|---|
make setup | uv sync |
make dev | uv sync --all-extras |
make test | uv run pytest |
make lint | uv run ruff check . |
make format | uv run ruff format . |
make docs-serve | uv run mkdocs serve |
make docs-build | uv run mkdocs build |
make build-and-publish | rm -rf dist/ && uv build && uv publish |
# Use a throwaway data dir so you don't clobber your real ~/.mcp_semantic_gateway
export MCP_SEMANTIC_GATEWAY_HOME=$(mktemp -d)
uv run mcp-semantic-gateway init
uv run mcp-semantic-gateway index
uv run mcp-semantic-gateway proxy
uv sync complains about Python version — repo pins >=3.12. pyenv install 3.12 and uv python pin 3.12 if needed.all-MiniLM-L6-v2 (~80 MB) is fetched from HuggingFace by sentence-transformers on the first index. Subsequent runs are offline.make format before committing. Pre-commit is not enforced, but CI runs ruff check.