golestan_code_mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@golestan_code_mcp who calls url_for in the flask repo?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: code-graph-mcp
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 connection2. 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 flask3. 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 flask4. Connect an AI coding tool. Install the command once, then register it. For Claude Code:
uv tool install --editable .
claude mcp add ccctx -- ccctx mcpAny 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 pytestMCP tools
Tool | Answers |
| Find code, wiki pages and remembered facts by name or by meaning |
| The full source of a definition |
| What calls a function or method |
| What a function or method calls |
| What could break if a definition changes |
| What a module does, from its wiki page |
| The indexed repositories |
| What earlier sessions worked out |
| 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.
Available Tools
9 toolsfind_calleesARead-only
What does this call? Lists the indexed symbols called from the body of each definition matching name, with the line of each call and where the called symbol is defined (repository, path, line range). Use it to follow what a function does one level down; for who calls it, use find_callers. Calls into code that is not indexed, such as the standard library or dependencies, are not listed. At most 200 rows; truncated is true when more exist. Next step: get_symbol on a callee to read it.
Inputs: name (required), repo. Returns: reason, status, results, truncated
find_callersARead-only
Who calls this? Lists every call to the definitions matching name: the calling symbol, its kind, the repository, path and line of the call, and which definition is called. Use it before changing a function's signature or behavior, to see its direct call sites. For everything a change could reach through chains of calls, use impact_of; for what this symbol itself calls, use find_callees. Calls come from the parse tree, so comments, docstrings and strings never count. A call at module level has kind file and name (module). At most 200 rows; truncated is true when more exist. Next step: get_symbol on a caller to read it.
Inputs: name (required), repo. Returns: reason, status, results, truncated
get_symbolARead-only
Read the full source of a named definition (function, method, class, type) when you know its name, for example from a search_code hit. Use this instead of search_code when the name is known, and instead of opening files: it returns the source exactly as it was indexed. A bare name returns every definition with that name, each labeled with its qualified name; pass a qualified name or a repo to narrow. Returns up to 5 matches, each with its qualified name, kind, repository, path, line range and source. A source longer than 400 lines is cut there and marked cut, and its full line range is still given. total is the number of matches and truncated is true when more than 5 matched. Unparsed files indexed as line windows have no names and are not found here; use search_code for them.
Inputs: name (required), repo. Returns: total, reason, status, results, +1 more
impact_ofARead-only
What could break if I change this? Lists every symbol that reaches the definitions matching name through calls in at most depth hops, once each at its shortest distance (hops), nearest first, with the repository, path and line range. Use it to gauge the reach of a change; for just the direct call sites and their lines, use find_callers. At most 200 rows; truncated is true when more exist. Next step: get_symbol on the nearest symbols to see how they use it.
Inputs: name (required), repo, depth. Returns: reason, status, results, truncated
list_repositoriesARead-only
Which codebases can I ask about? Lists the registered repositories with their paths and how many files and symbols each holds. Use it to learn the valid repo values for the other tools, or after a repo was refused. A repository with 0 files is registered but not indexed yet.
Inputs: no named parameters. Returns: reason, database, repositories
mark_usedAIdempotent
Tell the server a result helped: call this for each search hit you cite in your answer or rely on. Pass the hit's repo, path and name exactly as search_code returned them. Results that clients mark get a small, capped boost in later searches, and the boost fades over 30 days. Reading a hit with get_symbol or read_wiki already counts as a lighter use, so mark only what you actually used.
Inputs: name (required), path (required), repo (required). Returns: kind, name, path, repo, +3 more
read_wikiARead-only
What does this module do? Reads the tool's wiki page about a module (a directory of indexed code): its purpose, its key symbols with one line each, the modules it depends on and the modules that use it. Use it when a question is about a module as a whole rather than one function, or after search_code returns a hit of kind page. Pass page to read one page; it returns the text, whether it is fresh or stale (and what made it stale), when and by what it was compiled, and its citations, each with the repository, path and line range of the symbol or file it names. Omit page to list the pages, optionally for one repo, with each page's name, state and first purpose line. A stale page describes code that has changed since; check its citations. Next step: get_symbol on a key symbol to read its source.
Inputs: page, repo. Returns: page, pages, reason, status, +1 more
recallARead-only
Call this at the start of a session, and before searching, to load what earlier sessions already worked out about a codebase. Returns the stored facts, fresh first and most confident first, or most related to topic when one is given, and the most recent tool calls. Each fact has its subject (a symbol or wiki page), its text, a confidence from 0 to 1, whether it is fresh or stale (and why), what wrote its text (a configured model or the template distiller), the IDs of the runs it was distilled from, and the repository, path and line range of the code it describes. A stale fact describes code that has changed since; check it with get_symbol before relying on it. Facts are distilled from earlier calls by ccctx memory consolidate and after every ingestion. Next step: get_symbol on a fact's subject to read its source, or search_code for what recall does not cover.
Inputs: repo, limit, topic. Returns: runs, facts, total, reason, +2 more
search_codeARead-only
Find code by what it does or by name: "how are requests routed?", "where are sessions saved?", "url_for". Use this first when you do not yet know which symbol to look at. If you already know the name, use get_symbol to read it, find_callers for its call sites, or impact_of for what a change would affect. Returns up to limit hits (default 10), best first. Each hit has the repository, path, symbol name, kind, language, line range, a snippet of the symbol's opening lines, and the scores behind its rank: the score, the relevance (the score before feedback), the feedback boost, the keyword rank and the semantic rank (null when that side did not find it). The feedback field is the boost from earlier sessions marking the result used: at most 0.2 (20 percent), fading over 30 days; relevance is the score before it. Keyword and semantic search are fused, and the definitions of an exact identifier come first. A hit of kind page is a wiki page about a whole module: its name is the page name, its path is the module's directory, its line range is null and its state says whether it is fresh or stale; read it with read_wiki. A hit of kind fact is something an earlier session worked out about the code at its path; recall lists all of them. Next step: call get_symbol with a hit's name to read its full source, or read_wiki with a page hit's name.
Inputs: query (required), repo, limit, feedback, +1 more. Returns: reason, status, results
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a sharply distinct role: search by description, read by known name, read a module wiki page, direct callers vs callees, transitive impact, repository listing, session memory recall, and feedback marking. The descriptions explicitly cross-reference the neighbours (find_callers vs impact_of vs find_callees; search_code vs get_symbol) and state when to prefer each, eliminating overlap.
Most tools follow a verb_noun pattern (search_code, get_symbol, find_callers, read_wiki, list_repositories, mark_used). A few deviate: impact_of is noun/prepositional and recall is a bare verb, which is slightly inconsistent but still readable and unambiguous.
Nine tools sit comfortably in the well-scoped 3-15 range. Each maps to a distinct step in a code-investigation workflow (discover repo, search, read, navigate calls, gauge impact, consult/write memory), none feels redundant.
Covers the core lifecycle well: repository discovery, search, symbol/source reading, wiki pages, forward and backward call navigation, transitive impact, plus memory recall and feedback. Minor gaps exist—no way to enumerate symbols within a file or module, and no explicit tool to write/record a new fact (facts are distilled automatically), but agents can work around these.
Maintenance
Related MCP Connectors
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Search indexed code, trace dependencies, assess change impact, and recall repository memory.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceLocal-first code indexer that provides deep code understanding for Claude and other LLMs with symbol/text search across 48+ languages, semantic search capabilities, and real-time index updates through the Model Context Protocol.60MIT
- AlicenseNot gradedqualityBmaintenanceTurns a codebase into a queryable graph with semantic search, call graphs, and control/data flow analysis, served to AI coding agents via the Model Context Protocol.182 npmMIT
- AlicenseNot gradedqualityCmaintenanceProvides intelligent code indexing with 15 MCP tools for symbol extraction, hybrid search (FTS5+vector), call graphs, and incremental indexing of local folders and remote repos, enabling token-efficient code retrieval for AI agents.3MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to query a locally indexed structural code graph — source entities, callers/callees, Git relationships and recorded mistakes — so they retrieve focused, token-bounded context instead of reading entire files. It runs over local SQLite and can be served through a CLI, agent hooks, an MCP executable and an authenticated local dashboard.28 npmMIT