Semcode
@GoodbyePlanet
An MCP (Model Context Protocol) server providing hybrid semantic search over code across a set of GitHub repositories that you list in config.yaml. It parses symbols with Tree-sitter and indexes both code and git commit history, so AI clients can query them by natural language or
Overview
What is Semcode?
Semcode is an MCP server that provides hybrid semantic search over code across a set of GitHub repositories you list in config.yaml. It parses code symbols using Tree-sitter, indexes both source code and git commit history, and enables AI clients to query them by natural language or symbol name.
How to use Semcode?
Install Python 3.12+, Docker, and a GitHub token. Clone the repo, run uv sync, copy .env.example to .env and set GITHUB_TOKEN, then copy config.example.yaml to config.yaml and list the repositories to index. Start the server with make docker-up-jina (local embeddings) or make docker-up (hosted provider). Connect AI clients by pointing them at http://localhost:8090/mcp.
Key features of Semcode
- Hybrid retrieval combining dense embeddings and BM25
- Incremental indexing—only changed files are re-embedded
- Supports 19 programming languages with framework-aware parsing
- Optional git commit history indexing with full diffs
- MCP tools for search, symbol lookup, and reindexing
- HTTP API for triggering index from CI/CD pipelines
Use cases of Semcode
- Querying codebases by natural language (e.g., "where do we publish order events?")
- Finding symbol definitions and usages across multiple repositories
- Retrieving full source context for symbols within a file
- Searching git commit history to understand code evolution
- Generating architectural overviews of services via MCP prompts
FAQ from Semcode
What embedding providers does Semcode support?
The default is Jina Code V2 via a local TEI container (no API key needed). You can also use Voyage, OpenAI, or Ollama by setting the EMBEDDINGS_PROVIDER environment variable.
How does incremental indexing work?
Files are skipped when their Git blob SHA matches the last indexed version. Files that no longer exist or parse to zero symbols are cleaned up automatically. Pass force: true to re-embed everything.
What are the runtime requirements?
Python 3.12+, Docker (for Qdrant and optionally Jina TEI), and a GitHub personal access token with Contents: read on the target repositories.
Where does indexed data live?
Vectors and metadata are stored in a local Qdrant instance running in a Docker container with persistent volumes. Embeddings cache is also persisted.
How do I connect an AI client to Semcode?
Point your MCP client (Claude Desktop, Claude Code CLI, Cursor, etc.) to http://localhost:8090/mcp using the HTTP transport. The README includes configuration examples for several clients.
