Skip to main content
Glama
CodeIndex MCP

CodeIndex MCP

by doberkofler

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

tsconfig.json or jsconfig.json

TypeScript and JavaScript declarations, references, imports, exports, bindings, and diagnostics

oracle

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

codeindex-mcp

Host CLI, MCP server, console, core, loader

@codeindex/adapter-sdk

Language-neutral protocol, schemas, defineAdapter, conformance

@codeindex/adapter-typescript

TypeScript / JavaScript adapter and typescript dependency

@codeindex/adapter-oracle

Static Oracle adapter and antlr4ng dependency

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 status

The 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.json

All 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.json

This 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-legacy

Migration 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.json

Add --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

index_status

Readiness, configured adapters and scope, coverage, counts, freshness, limitations, and last error

outline

Declarations in one indexed file, in source order

find_symbol

Exact or prefix declaration lookup

find_references

References or definitions for a symbol ID, or one-call name resolution grouped by file or owner

find_dependencies

Direct external dependency consumers or transitive authored-module impact

read_symbol

Bounded source or binding/definition-site metadata for one symbol

symbol_at

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 it

Index-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 --open

It 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

CODE_INDEX_CONFIG

Configuration file path

CODE_INDEX_ROOT

Workspace root

CODE_INDEX_EXTRACTOR

Extractor ID

CODE_INDEX_PROJECT_FILE

Single extractor project-file override

CODE_INDEX_DATABASE

SQLite database path

CODE_INDEX_ANALYTICS

0 or false disables analytics writes

CODE_INDEX_ANALYTICS_PATH

Analytics JSONL path

CODE_INDEX_LOG

Legacy alias for the analytics path

CODE_INDEX_MAX_RESULT_BYTES

Maximum MCP response size

CODE_INDEX_MAX_READ_LINES

Maximum source lines returned by read_symbol

CODE_INDEX_BUILD_WORKER_IDLE_MS

Idle timeout for the persistent build worker

CODE_INDEX_BUILD_WORKER_MAX_RSS_BYTES

Process-tree RSS ceiling before the worker restarts

CODE_INDEX_SEMANTIC_DIAGNOSTICS

1 or true enables TypeScript semantic diagnostics

CODE_INDEX_PROJECT_ID

Reported stable logical project ID

CODE_INDEX_LOG_LEVEL

debug, info, warn, or error

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. Run codeindex-cli update --config <path> and inspect status --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 run codeindex-cli update; never treat previously returned source as current.

  • Oracle configuration failure: Oracle requires extractor.project or extractor.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

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Indexes 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.
      6
      117 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local, SQLite-backed code index for Claude Code, exposed over MCP, enabling targeted code retrieval without external APIs.
      112 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to perform local code search, indexing, and analysis across Java, JavaScript/TypeScript, .NET/C#, and Python projects through the MCP protocol.
      1
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      -