code-context-mcp

golestan_code_mcp

A code context MCP server backed by Oracle AI Database 26ai. It indexes codebases into the database, cut at function and class boundaries. It searches them by name and by meaning, follows their calls, keeps a wiki page about each module, and remembers what earlier sessions learned. It serves all of it to AI coding tools such as Claude Code, Codex and Cursor over the Model Context Protocol (MCP), so an agent can find and understand code without reading whole files.

The idea was initiated by the article Coding Challenge #139 - Code Context from Coding Challenges. The project was developed with the help of GitHub Spec Kit: every feature went through a specification, a plan and a task list, kept in specs/.

It is free to use, change and share under the MIT License.

Features

• Structure-aware indexing of 13 languages (Python, Go, JavaScript, TypeScript, C#, C, C++, Java, Kotlin, Rust, PHP, Ruby, Swift): one chunk per definition, with its exact lines and documentation. Re-ingesting only reads what changed.
• Hybrid search: keyword and semantic matching fused in one database index, with each result's scores shown.
• Code graph: callers, callees and the transitive impact of a change, as a SQL property graph.
• Module wiki: one page per module, written from the index, with citations that follow the code and pages that are rewritten when it changes.
• Agent memory: every tool call is recorded and distilled into facts a new session can recall.
• Usage feedback: results that clients used rank a little higher, with a bounded, decaying boost.
• Private by default: embeddings are computed inside the database, so no source code is sent out to be indexed and no API key is needed.

Quick start

You need Docker (tested with Rancher Desktop) with about 12 GB free, uv and git. The commands are run from the project root; Setup has the details and the PowerShell variants.

1. Configure and start the database. Copy .env.example to .env and replace both passwords. Then:

docker compose up -d
uv sync
uv run golestan-check-db       # waits for the first start, then checks the connection

2. Index a repository. Indexing explains what is read and how re-ingesting works.

uv run golestan-clone-samples                         # optional: flask and gin, into ../ccctx-repos
uv run ccctx repo add ../ccctx-repos/flask --name flask
uv run ccctx model load                               # once: the embedding model and the search index
uv run ccctx ingest flask

3. Search it. See Search and Code relationships.

uv run ccctx search "how are incoming requests routed to handlers"
uv run ccctx callers url_for
uv run ccctx wiki build --repo flask

4. Connect an AI coding tool. Install the command once, then register it. For Claude Code:

uv tool install --editable .
claude mcp add ccctx -- ccctx mcp

Any MCP client can start ccctx mcp the same way. The MCP server has the details.

Upgrading from 1.4.1 or earlier. The source moved from src/golestan_code_mcp/ to src/, so an existing install must be refreshed once: close the MCP clients that run ccctx (on Windows they keep ccctx.exe locked), then run uv sync and uv tool install --editable . --reinstall. Registrations stay as they are.

5. Run the tests. Database tests are skipped, with a reason, when the database is down.

uv run pytest

MCP tools

Tool	Answers
search_code	Find code, wiki pages and remembered facts by name or by meaning
get_symbol	The full source of a definition
find_callers	What calls a function or method
find_callees	What a function or method calls
impact_of	What could break if a definition changes
read_wiki	What a module does, from its wiki page
list_repositories	The indexed repositories
recall	What earlier sessions worked out
mark_used	Record that a result helped

Parameters, results and the change history are in The MCP server.

Documentation

• Setup: prerequisites, the database, installing, checking that data persists
• Indexing: registering and ingesting codebases, the languages and their limits
• Search: search modes and ranking, usage feedback, evaluating retrieval
• Code relationships: callers, calls and impact
• Module wiki: the module pages, their citations and how they stay current
• Agent memory: runs, facts, recall and the optional distilling model
• The MCP server: the tools, registering clients, the change history
• CLAUDE.md: commands, conventions and the file layout, for AI coding agents and contributors

License

MIT, see LICENSE.