CodeIndex MCP
Indexes JavaScript projects when allowJs is enabled, enabling the same code navigation, symbol search, reference lookup, dependency analysis, and bounded source reading capabilities.
Indexes TypeScript projects to provide code outlines, symbol search, reference lookup, dependency analysis, and bounded source reads across a TypeScript codebase.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
CodeIndex MCP
CodeIndex MCP is a local, read-only code index for AI coding clients. It indexes one configured workspace into SQLite and exposes bounded navigation through MCP, a command-line interface, and a loopback management console.
Use it to locate declarations, inspect a file outline, find references, trace dependency use, resolve the declaration at a source position, and read the smallest useful source range without loading an entire repository into context.
Supported source
Extractor | Input | Current coverage |
|
| TypeScript and JavaScript declarations, references, imports, exports, bindings, and diagnostics |
| Explicit Oracle manifest | Oracle 19c packages, standalone procedures/functions, tables, table columns, views, references, and package dependencies |
JavaScript requires allowJs in the selected TypeScript project. Declaration
files and generated output may participate in compiler resolution but are not
published as authored source.
The Oracle extractor reads static source only; it does not connect to Oracle at runtime. Object types, triggers, synonyms, database links, inferred view columns, SQL object lineage, wrapped source, and conditional-compilation branch evaluation are not indexed.
One server may index several adapters. A multi-adapter workspace shares one
database, build lease, and published generation, and each read tool accepts an
adapter filter; cross-language edges are not indexed.
Related MCP server: code-index
Requirements and installation
Node.js 26 or newer.
The tarballs attached to a GitHub release tag. CodeIndex and its official adapters are not published to npm.
Install an immutable release in the consuming project:
VERSION=0.12.0
BASE="https://github.com/doberkofler/codeindex-mcp/releases/download/v${VERSION}"
pnpm add \
"$BASE/codeindex-mcp-${VERSION}.tgz" \
"$BASE/codeindex-adapter-sdk-0.1.0.tgz" \
"$BASE/codeindex-adapter-typescript-0.1.0.tgz" \
"$BASE/codeindex-adapter-oracle-0.1.0.tgz"The adapters depend on @codeindex/adapter-sdk@0.1.0, which is not in the npm
registry. pnpm does not resolve that nested range against the directly installed
tarball, so pin the same artifact in the consumer's pnpm-workspace.yaml:
overrides:
"@codeindex/adapter-sdk": "https://github.com/doberkofler/codeindex-mcp/releases/download/v0.12.0/codeindex-adapter-sdk-0.1.0.tgz"npm resolves the nested range against the directly installed copy and needs no override.
Do not install a Git tag directly: the host and adapter manifests use the pnpm
workspace: protocol, and the adapter packages ship built output only.
oracledb is used only by opt-in live Oracle qualification; normal Oracle
indexing opens no Oracle connection.
Installation topology
CodeIndex is distributed as independent ESM packages:
Package | Responsibility |
| Host CLI, MCP server, console, core, loader |
| Language-neutral protocol, schemas, |
| TypeScript / JavaScript adapter and |
| Static Oracle adapter and |
Install only what a workspace needs; a TypeScript-only workspace omits the Oracle adapter tarball, and an Oracle workspace omits the TypeScript adapter.
The host has no runtime dependency on a language adapter. An unconfigured
adapter is never installed or bundled. Official adapter IDs normalize to their
package names, so id: "typescript" and id: "oracle" keep working without a
module field. A missing package fails before transport startup with
adapter_module_not_found and names the package to install.
Adapter packages are trusted code: installing one grants the same filesystem, environment, and network authority as the CodeIndex process.
This is a major installation change: the previous single-package Git install no longer supplies every adapter. Roll back by pinning a host release together with the adapter versions it was verified against.
Quick start
From a TypeScript workspace containing tsconfig.json, the defaults are enough:
codeindex-cli update
codeindex-cli statusThe default extractor is typescript, the default root is the current directory,
and the default project file is tsconfig.json.
For explicit or multi-project configuration, create codeindex.config.json:
{
"project": {
"name": "my-workspace",
"root": "."
},
"extractors": [
{
"id": "typescript",
"required": true,
"projects": [
{"name": "browser", "project": "tsconfig.json"},
{"name": "server", "project": "server/tsconfig.json"}
]
}
],
"limits": {
"maxResultBytes": 32768,
"maxReadLines": 200
},
"freshness": {
"debounceMs": 1000,
"adapters": {
"typescript": {"debounceMs": 3000}
},
"workerIdleMs": 60000,
"workerMaxRssBytes": 2147483648
}
}The legacy singular extractor object remains valid and normalizes to one required
adapter. With extractors, every adapter shares one database, build lease, and
published generation; required defaults to true, and only an optional adapter
may report declared absence. The two forms are mutually exclusive.
freshness.debounceMs is the workspace default quiet period after the last
filesystem event before a rebuild starts (100–10000 ms, default 1000).
freshness.adapters.<id>.debounceMs overrides it for one configured adapter; unknown
adapter IDs and values outside the same range are rejected. Events keep restarting
only the owning adapter's absolute deadline, so a burst of editor saves becomes one
rebuild without delaying unrelated work whose deadline already elapsed. Raise the
value for expensive builds or generators; lower it for small, interactive
workspaces. Events are routed to the adapter that owns the changed path; a targeted
refresh probes, scans, extracts, and writes only that adapter. Shared configuration
changes and ambiguous paths still invalidate every adapter.
freshness.workerIdleMs and freshness.workerMaxRssBytes bound the persistent
build worker. The worker and its compiler session stay warm between refreshes, are
stopped after the idle timeout, and are restarted when the whole process tree,
including compiler child processes, exceeds the RSS ceiling. TypeScript sessions
also accept extractors[].options.warmIdleMs to override their own idle timeout
(default 60000 ms; 0 keeps the session until shutdown).
Each entry may name an adapter module. A bare package name resolves from the
configuration-file directory; a relative path resolves from the same directory.
Absolute paths and URL schemes are rejected. Without module, the official IDs
typescript and oracle use the built-in compatibility aliases.
{
"extractors": [
{
"id": "custom",
"module": "@example/codeindex-adapter-custom",
"required": true,
"project": "custom-project.json"
}
]
}An adapter module exports one named codeIndexAdapter with a manifest and
factory; the host validates the protocol version, adapter ID, implementation
version, and factory result before scanning.
Then build or reuse the index:
codeindex-cli update --config codeindex.config.jsonAll configured adapters and their project contexts share one publication boundary. Context names are adapter-scoped and appear in results; the same name may exist under two adapters.
Paths in a configuration file resolve relative to that file. Environment and CLI path overrides resolve relative to the current working directory. Project files must stay inside the workspace; database and analytics paths must stay outside it.
Connect an MCP client
OpenCode
Install a project-local server entry while preserving unrelated JSONC content:
codeindex-cli mcp install \
--root . \
--codeindex-config codeindex.config.jsonThis writes exactly one mcp.servers.codeindex entry to the existing project
OpenCode configuration, or creates .opencode/opencode.jsonc. The key does not
change with the configured adapters. The entry records the absolute project root
as its cwd, so OpenCode resolves the relative bundle and CodeIndex configuration
paths from the repository root even when a session starts in a nested directory of
a monorepo. Re-run mcp install after moving the checkout, because that cwd is
an absolute path. Reconnect the MCP server after installation or an upgrade.
Older releases registered one key per adapter, such as codeindex-oracle.
mcp install refuses to write while such legacy keys remain. When the registered
command proves CodeIndex created the entry for this configuration, migrate it:
codeindex-cli mcp install \
--root . \
--codeindex-config codeindex.config.json \
--migrate-legacyMigration never removes an entry whose command and arguments differ from what this invocation would write; remove or rename those entries manually.
Remove only the canonical server entry with:
codeindex-cli mcp uninstall \
--root . \
--codeindex-config codeindex.config.jsonAdd --legacy to remove legacy entries whose command proves CodeIndex created
them for this configuration.
--config on the mcp subcommand selects the OpenCode configuration to edit;
--codeindex-config selects the configuration passed to CodeIndex.
Other MCP clients
Configure a local stdio server whose working directory is the indexed workspace:
{
"mcp": {
"servers": {
"codeindex": {
"type": "local",
"command": [
"codeindex-mcp",
"--config",
"codeindex.config.json"
]
}
}
}
}codeindex-mcp reserves stdout for MCP framing. Its version banner,
diagnostics, and debug traces go to stderr.
MCP tools
The server exposes seven read-only tools:
Tool | Use |
| Readiness, configured adapters and scope, coverage, counts, freshness, limitations, and last error |
| Declarations in one indexed file, in source order |
| Exact or prefix declaration lookup |
| References or definitions for a symbol ID, or one-call name resolution grouped by file or owner |
| Direct external dependency consumers or transitive authored-module impact |
| Bounded source or binding/definition-site metadata for one symbol |
| Innermost stored declaration covering a source line or position |
Responses include freshness and explicit guidance. When
guidance.action is stop and fallbackRequired is false, the current,
untruncated result is authoritative. Follow nextCursor whenever truncated is
true. Use ordinary repository tools when guidance requests fallback or the fact is
outside indexed scope.
Every read tool accepts an optional adapter filter. Omitting it searches every
configured adapter; results name the owning adapter on each item. Project contexts
are adapter-scoped: a bare context name that exists under more than one adapter
fails with ambiguous_context and requires both adapter and context. outline
and symbol_at infer the adapter from the path, and an explicit filter must match
or the call fails with adapter_path_mismatch.
outline and find_symbol return compact results by default. Request full detail
only for bindings, qualified names, or definition sites. Every response is bounded
by maxResultBytes; source is also bounded by maxReadLines.
read_symbol checks the current file hash before returning persisted source. A
dirty or changed path returns stale_file instead of stale text.
Oracle configuration
Select the Oracle extractor and name an explicit manifest:
{
"project": {
"name": "database-source",
"root": "."
},
"extractor": {
"id": "oracle",
"project": "oracle-index.json"
}
}Example oracle-index.json:
{
"schemaVersion": 1,
"dialect": "19c",
"defaultSchema": "APP",
"extensions": [".pks", ".pkg", ".pkb", ".prc", ".fnc", ".sql"],
"include": ["database/**/*"],
"exclude": ["**/generated/**"]
}Patterns are workspace-relative POSIX globs. extensions is optional; when
omitted it defaults to .pks, .pkg, .pkb, .prc, and .fnc. Add .sql or
.pls when those files should be published.
Unquoted Oracle names use canonical uppercase spelling; quoted names preserve
authored spelling. Natural qualified queries such as PACKAGE_NAME.ROUTINE_NAME
are accepted.
CLI
Common operational commands:
codeindex-cli update # build only when source or configuration changed
codeindex-cli refresh # alias for update
codeindex-cli rebuild # force extraction and publication
codeindex-cli status # generation, scope, counts, and freshness
codeindex-cli verify # SQLite integrity, foreign keys, and stored counts
codeindex-cli analytics # report local privacy-safe analytics
codeindex-cli audit # inventory managed storage and generated artifacts
codeindex-cli clean # list the current database; add --yes to remove itIndex-backed operational commands accept --config, --root, --extractor,
--project-file, --database, --json, and --debug where applicable.
clean resolves its target from the environment; set CODE_INDEX_CONFIG when
cleaning a non-default project.
Benchmark, soak, TypeScript differential, publication measurement, Oracle
qualification, evidence preflight, and replay commands are maintainer surfaces.
Run codeindex-cli --help and codeindex-cli <command> --help for their current
options. Retained Oracle commands and evidence are documented in
benchmark/oracle-production-20261027
and benchmark/oracle-performance.
Console
Start the loopback-only management console:
codeindex-console --config codeindex.config.json --openIt binds to 127.0.0.1, uses a random per-run bearer token, and can show status,
freshness, and analytics or run operational jobs. --port 0 selects an available
port.
Environment overrides
Variable | Effect |
| Configuration file path |
| Workspace root |
| Extractor ID |
| Single extractor project-file override |
| SQLite database path |
|
|
| Analytics JSONL path |
| Legacy alias for the analytics path |
| Maximum MCP response size |
| Maximum source lines returned by |
| Idle timeout for the persistent build worker |
| Process-tree RSS ceiling before the worker restarts |
|
|
| Reported stable logical project ID |
|
|
Storage and privacy
By default, each physical checkout gets a separate directory under
~/.local/share/codeindex-mcp/. Moving or copying a checkout produces a different
storage key, so it cannot silently reuse another checkout's database or lease.
The SQLite database is disposable derived data and contains indexed source bytes for freshness-safe reads. Schema incompatibility moves the old database aside and rebuilds; there are no in-place migrations.
Analytics are local, bounded, versioned, and enabled by default. They contain
operation names, timings, counts, byte sizes, freshness, and stable error codes;
they exclude source text, prompts, queries, symbol names, credentials, and
absolute paths. Set CODE_INDEX_ANALYTICS=false to disable writes.
Git and SVN provenance is recorded when available. An unversioned workspace is fully supported; freshness is hash-based, not VCS-based.
codeindex-cli audit inventories managed indexes, analytics, schema backups,
repository-generated output, benchmark caches, evidence bundles, and evaluation
state without deleting or modifying anything. It discovers XDG and repository
storage locations, reports active index owners and dirty Git worktrees, and
normalizes retained paths to $HOME and $REPO. .git and worktree
registrations are reported separately and excluded from artifact totals. On
macOS, byte totals use APFS allocated blocks; other platforms use logical file
size. OpenCode session storage is never inspected.
Every managed category has one documented bound. codeindex-cli clean --all
reclaims stale benchmark workspaces and scratch databases, unreferenced benchmark
project checkouts, superseded Oracle evidence bundles, and old evaluation state.
It keeps the Oracle bundle the bundle gate requires, refuses active owners,
protected paths, and dirty worktrees, and prunes stale Git worktree
registrations. See retention for the bound and
enforcement path of each category.
Troubleshooting
index_not_ready: the initial background build has not published. Runcodeindex-cli update --config <path>and inspectstatus --json.index_build_failed: inspect MCP stderr or CLI output. The previous published revision remains available when one exists.file_not_indexed: confirm that the file is reachable from a configured TypeScript project or included by the Oracle manifest.stale_file: wait for the watcher to publish the change, or runcodeindex-cli update; never treat previously returned source as current.Oracle configuration failure: Oracle requires
extractor.projectorextractor.projects; it never guesses a manifest.No MCP output: stdout is protocol-only. Read stderr, or enable
DEBUG=codeindex:*for namespaced traces.Changed server code or dependency version: rebuild when developing locally, then restart or reconnect the MCP process. A running process keeps the bundle it started with.
Project documentation
Architecture — how the current implementation works.
Enhancements — index of open work; GitHub issues hold requirements and acceptance criteria.
Contributing — development setup, checks, and contribution rules.
Evaluation — controlled evaluation contracts and retained reports.
Verification workflows — CI, nightly, stable, and release operations.
Third-party notices — vendored Oracle grammar provenance and licenses.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Stateless TS/JS compiler facts for agents: references, imports, impact. No repo index or OAuth.
Related MCP Servers
- AlicenseAqualityBmaintenanceIndexes codebases into a SQLite database to provide metadata, exports, dependency graphs, and change tracking for JS/TS projects. It enables users to search for symbols, map internal dependencies, and monitor file changes through MCP tools and a web dashboard.6117 npm5MIT
- AlicenseNot gradedqualityDmaintenanceA local, SQLite-backed code index for Claude Code, exposed over MCP, enabling targeted code retrieval without external APIs.112 PyPI1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to perform local code search, indexing, and analysis across Java, JavaScript/TypeScript, .NET/C#, and Python projects through the MCP protocol.1Apache 2.0
- FlicenseNot gradedqualityDmaintenanceProvides code intelligence by indexing source code into SQLite and offering MCP tools for symbol search, flow tracing, and context retrieval to assist with code navigation and understanding.-