codesearch
OfficialProvides a VS Code extension and MCP server for index-based code search within GitHub Copilot.
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.
codesearch
Full-text and structural code search for a large monorepo. Runs an in-process Tantivy index (via tantivy-py) and exposes results as MCP tools so coding agents, including GitHub Copilot in VS Code, can query the codebase directly without copy-pasting.
Early alpha. Expect rough edges.
Installation
git clone https://github.com/microsoft/tscodesearch
cd tscodesearch
setup.cmd
ts startsetup.cmd creates a Python venv (via uv), registers the MCP server with Claude Code and VS Code (GitHub Copilot), prompts for a source directory to index, creates config.json, and installs the VS Code extension.
To add a local, user-level Copilot instruction that critically prioritizes
tscodesearch for files in the local working tree or configured roots, run
setup.cmd --priority. The instruction limits Bluebird usage to queries that
target checked-in repository state or code in another source tree. Setup writes
the instruction to ~/.copilot/copilot-instructions.md; it is not added to the
indexed repository.
To uninstall: setup.cmd --uninstall
Related MCP server: Fast Context MCP
GitHub Copilot and VS Code Chat
The repository includes:
AGENTS.mdfiles for repository-wide and project-scoped agent guidance.github/copilot-instructions.mdfor Copilot instruction discovery.github/instructions/for file-scoped Copilot guidance.mcp.jsonfor portable workspace MCP discoveryvscode-codesearch/.vscode/mcp.jsonwhen the extension folder is opened as a standalone workspace
The workspace MCP configurations use repository-relative paths and become
available after setup.cmd creates .venv. Setup also registers the
same uv-backed stdio MCP server in $COPILOT_HOME/mcp-config.json (default:
~/.copilot/mcp-config.json) using the current portable mcpServers format.
It also keeps a VS Code user-profile mcp.json registration for Local harness
compatibility. Tools remain available when working in separately indexed
repositories. Uninstall removes both registrations.
VS Code asks you to trust local MCP servers before starting them. Review the configuration and approve it only for a trusted checkout.
Prerequisites
Windows 11 (or Linux/macOS for the daemon, with caveats)
Python 3.12, installed and managed automatically by uv
Node.js 22+
VS Code 1.144.0+ for the extension
uvis installed automatically bysetup.mjsif missing
There is no Docker, WSL, or Typesense dependency. The whole index is in-process.
Python dependencies are locked in uv.lock. Node dependencies are managed only
in vscode-codesearch/package.json and its lockfile; the repository root does
not have a Node package. The extension overrides minimatch to a patched
release because the current packaging tool still requests an affected version.
One-time setup
From a Windows command prompt or PowerShell:
setup.cmdsetup.cmd checks for Node.js then calls node setup.mjs, which:
Ensures uv is installed (using winget on Windows), installs the managed Python version from
.python-version, and synchronizes.venvfrom the lockfileRegisters the uv-backed MCP server with Claude Code, Copilot (
mcp-config.json), and VS Code Local (mcp.json)Creates
config.json-- prompts for a source directory to index (can be added later)Installs the VS Code extension
Pass --priority to also install the local Copilot search-priority instruction:
setup.cmd --priorityAfter setup, start the daemon:
ts startTo uninstall: setup.cmd --uninstall
Adding roots
ts root --add NAME C:\path\to\source
ts restartOr use the VS Code extension command TsCodeSearch: Add Root.
Each root gets its own on-disk Tantivy index at <repo>/.tantivy/codesearch_NAME/. Multi-root config in config.json:
{
"api_key": "...",
"port": 8108,
"roots": {
"default": { "path": "C:/myproject/src" },
"other": { "path": "D:/other/src" }
}
}Each root entry can be either an object ({"path": "...", "extensions": [".cs", ".py"]}) or a bare string ("C:/myproject/src"). The object form is what setup.mjs writes and what ts root --add produces; the string form is accepted for backwards compatibility.
Use the MCP root= parameter to search a specific collection:
query_codebase("implements", "IRepository", root="other")
query_single_file("methods", file="path/to/Widget.cs", root="other")Daemon management
All daemon commands go through ts.cmd (Windows CMD/PowerShell):
ts status show daemon health, doc count, watcher state
ts start start the daemon (auto-indexes on first run)
ts stop stop the daemon
ts restart stop then start
ts verify scan FS + repair index: add missing, re-index stale, remove orphans
ts verify --root <name> verify a specific named root
ts verify --no-delete-orphans repair without removing deleted-file entries
ts recreate stop daemon, wipe the on-disk index, restart (full reindex)
ts recreate --root <name> recreate a specific named root's index
ts log [-n N] tail the daemon log (default: last 40 lines)Keeping the index up to date
The watcher picks up changes automatically within a couple of seconds (~1 s ReadDirectoryChangesW latency + 2 s debounce). For large repos, or after bulk operations like a git pull or branch switch, use the MCP tools or ts verify to confirm everything is in sync.
From MCP clients
ready() # quick daemon/index/watcher snapshot
service_status() # document count for each configured root
wait_for_sync(timeout_s=30) # poll until queue drained; pass 0 for instant statusready() returns the document count, watcher state, and pending queue depth without walking
the filesystem. Use ts verify when a branch switch, bulk rewrite, or watcher outage requires
a full filesystem-to-index repair.
wait_for_sync sleeps up to 1 s (watcher warm-up) then polls /status every 0.5 s until the queue is empty. Reports "Index synced in {N}s" with a "was: queue={N}" note if work was observed, or a timeout message with recovery hints.
The MCP server starts immediately and requests daemon startup in the background when needed.
If the daemon disconnects during a tool call, the MCP server attempts one restart and retry.
Runtime diagnostics are written to %LOCALAPPDATA%\tscodesearch\mcp_server.log; fatal Python
diagnostics go to mcp_crash.log, and daemon bootstrap output goes to daemon_startup.log.
From the command line
ts verify # foreground repair scan (missing + stale + orphans)
ts verify --no-delete-orphans # repair without removing deleted-file entries
ts verify --root other # verify a specific named rootRunning tests
All Python management and invocation uses uv directly with a single .venv
at the repository root. Run uv run --no-sync python ... from the root;
from another directory, use uv run --no-sync --project <repo> --directory <repo> python ....
There is no Node Python wrapper or separate client environment.
Runtime commands do not install or update packages while a daemon is running.
To synchronize development dependencies first (stop the daemon before syncing):
ts stop
uv sync --locked --managed-pythonuv run --no-sync python -m pytest tests/ query/tests/ -v # full Python suite
node --test tests/*.mjs # uv / MCP / daemon lock tests
node run_tests.mjs # VS Code extension testsThe integration tests open a fresh Tantivy index in <repo>/.tantivy/test_* for each class and clean up afterwards. No external service needs to be running.
Named Windows daemon
Setup creates .venv\Scripts\tscodesearch.exe from uv-managed Python's native
pythonw.exe and stages its runtime DLLs alongside it. This is the actual
daemon process image, not a launcher that spawns python.exe, so Task Manager's
Details tab shows tscodesearch.exe. It uses the same root .venv and is
launched through uv run --no-sync. Other Python commands and MCP servers
continue to use uv run --no-sync python.
Setup refreshes the executable after syncing Python. To create or refresh it without the rest of setup, stop the daemon first, then run:
ts stop
node scripts\create_daemon_exe.mjs
ts startThe executable retains Python's embedded icon and version metadata; the
daemon's custom system-tray icon is unchanged. Linux/macOS continue to use
uv run --no-sync python for the daemon.
File / dir | What it tests |
| All language AST query modes against synthetic fixtures |
| Indexer, queue, watcher, verifier, MCP server helpers -- all use |
| Indexer, verifier, watcher, search modes, sample E2E -- open real Tantivy indexes |
Direct CLI usage
Management API via curl
# Read key/port from config.json -- never hard-code
API_KEY=$(node -e "const c=require('./config.json'); process.stdout.write(c.api_key)")
API_PORT=$(node -e "const c=require('./config.json'); process.stdout.write(String(c.port??8108))")
curl -s -X POST http://localhost:$API_PORT/query-codebase \
-H "Content-Type: application/json" -H "X-API-KEY: $API_KEY" \
-d '{"mode":"declarations","pattern":"SaveChanges","root":""}' | uv run --no-sync python -m json.toolThe daemon authenticates every request by matching the X-API-KEY header against config.json's api_key. The HTTP server binds localhost only, but the key still matters: any process on the same machine -- a browser background page, another dev tool, a malicious dependency -- can reach localhost:PORT. Requiring a shared secret means a random local process can't query or mutate the index without first reading config.json.
Standalone search CLI (scripts/search.py)
uv run --no-sync python scripts\search.py "Widget" --ext cs --limit 5
uv run --no-sync python scripts\search.py "IRepository" --implementsThis opens the on-disk Tantivy index in read-only mode, so it works whether or not the daemon is running.
AST queries without a daemon (uv run --no-sync python -m query)
uv run --no-sync python -m query --mode methods --file C:/myproject/src/Widget.cs
uv run --no-sync python -m query --mode calls --file C:/myproject/src/Widget.cs --pattern SaveChangesAST query modes
One canonical mode name per concept across every language. Listing modes take no pattern; pattern modes expect a single identifier (or LINE:COL for at). Unknown modes raise ValueError with the supported-mode list -- use capabilities to introspect which modes a given file's language actually supports.
Mode | Arg | Concept | Languages |
| -- | List the modes supported for this file's language | all |
| -- | Type declarations (class/interface/struct/enum/record/...) | all |
| -- | Method/ctor/property/field/event declarations | all |
| -- | Field / property / column declarations | C#, SQL |
| -- |
| all except SQL |
| METHOD | Parameter list for METHOD | C#, Python, JS, Rust, C++ |
| NAME | Declaration(s) of NAME (narrow with | all |
| NAME | Full source of NAME's declaration | C# only |
| LINE:COL | Deepest AST node at position + enclosing scope chain | C# only |
| METHOD | Call sites of METHOD ( | all |
| TYPE | Types that inherit/implement TYPE | all except SQL |
| TYPE | Type references; narrow with | C# only |
| TYPE |
| C# only |
| NAME? |
| C#, Python, JS |
| MEMBER | Access sites of property/field by name ( | C# only |
| TYPE |
| C# only |
| NAME | Every identifier occurrence (broadest -- AST-only, skips strings/comments). For SQL this is a plain substring scan over lines. | all |
Architecture
Two-layer search
Tantivy -- fast keyword/semantic search over pre-indexed metadata (class names, method names, base types, call sites, signatures, attributes, etc.). Data stored at
<repo>/.tantivy/<collection>/.tree-sitter -- precise AST queries on the file set returned by Tantivy. Skips comments and string literals, understands syntax.
Typical flow: Tantivy narrows the haystack to ~50 candidate files -> tree-sitter parses each one and applies the structural query.
Process topology
,----------------------------------------------------------------,
| MCP CLIENT (Claude <-> tools) |
| mcp_server.py (.venv -- runs on Windows) |
| Claude Code -> mcp.cmd -> uv run -> root .venv |
`------------------------------T-----------------------------------'
| HTTP localhost:PORT
,-----------------------------v----------------------------------,
| DAEMON indexserver/daemon.py (.venv) |
| * HTTP server (management API on PORT) |
| * watcher (ReadDirectoryChangesW) |
| * IndexQueue (batch Tantivy writes) |
| * syncer (on-demand, via POST /verify/start) |
| * Tantivy indexes (one per root, on disk in .tantivy/) |
| * system-tray icon (Windows -- shows Stop menu item) |
`----------------------------------------------------------------'There is no longer a separate Typesense / Docker / WSL service -- the index lives in-process via tantivy-py. On Windows the daemon runs without a console window; right-click the magnifying-glass tray icon to stop it.
File map
File | Purpose |
| Python MCP server (FastMCP). Tools: |
| Management daemon. Owns the HTTP API, watcher, IndexQueue, syncer, system-tray icon, and one Tantivy |
| Windows launcher: |
| Shared uv command arguments for Node orchestration; spawns uv directly |
| Daemon CLI: start/stop/restart/status/index/verify/log/root |
| One-time setup: |
| VS Code extension test runner |
AST query layer (query/)
File | Purpose |
| Per-language tree-sitter AST functions |
| Shared dataclasses + |
| Pure query dispatcher. |
| CLI: |
TreeIndex walks the AST once with tree-sitter's TreeCursor, buckets nodes by type, and (optionally) collects literal-aware identifier refs in the same pass. describe_*_file covers the union of types every extractor needs in one walk; per-query wrappers (q_classes, q_methods, ...) pass a narrow type set so they pay the cost of a single targeted walk.
Indexer (indexserver/)
File | Purpose |
| Tantivy schema + |
| Typesense-shaped |
|
|
|
|
|
|
| Deduplicated batch queue. Writes go through a |
| Management daemon: HTTP server, watcher thread, IndexQueue worker, syncer, tray icon. |
| Structural query CLI ( |
Config
File | Purpose |
|
|
Scripts / infra
File | Purpose |
| Standalone read-only search CLI. |
Backend schema
Every text field uses Tantivy's raw tokenizer: each entry is one verbatim term (case-sensitive, no underscore splitting, no length cap). All domain-aware splitting happens in the indexer before storage -- long identifiers stay whole, add_text_field is one token, Acme.Billing.Service is three namespace entries.
Indexed search fields -- populated by the AST extractors and indexed for query_by matching; stored=False, so values are not retrievable from a search hit:
Field | Populated from | Used by MCP mode |
| base classes + interface lists |
|
| every call expression's method name |
|
| declared field / property / event types |
|
| method / ctor / delegate parameter types |
|
| method / delegate return types |
|
| declared local variable types |
|
|
|
|
| union of |
|
| RHS of |
|
| every identifier in any member signature -- attribute names, parameter names, generic args, default-value identifiers | -- (auxiliary; covers signature content) |
|
|
|
|
|
|
| per-component split of the file's primary namespace (e.g. | -- (auxiliary) |
| type and method/property/field declarations |
|
| deduped bag of every identifier in the file (code only -- no strings or comments) |
|
| per-directory + filename components -- | every mode (path/filename fallback) |
Stored fields -- retrievable from the index at search time:
Field | Purpose |
| Document identity, returned with every hit. |
| Basename, used for display. |
| Exact-match filters ( |
| Cumulative ancestor folders for the |
| Verifier diff between filesystem and index. |
Nothing else is stored. The daemon pre-filters with Tantivy then runs tree-sitter on the candidate files; the AST output is what carries line-level results to the caller. Display-only stored payload would just bloat the index.
The daemon resolves query_by/weights server-side from the mode (and uses_kind / symbol_kind when relevant); callers don't pass these directly through /query-codebase. See _resolve_query_params in tsquery_server.py for the exact mapping.
config.json
{
"api_key": "codesearch-local",
"port": 8108,
"roots": {
"default": { "path": "C:/myproject/src" }
}
}This file is not checked in (listed in .gitignore). It is created by setup.mjs with an auto-generated API key. Roots use Windows-style paths (C:/...) and are added via ts root --add or the VS Code extension. Root entries may also be bare strings -- see Adding roots above.
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
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides structural code intelligence via 26 MCP tools, enabling AI assistants to query code symbols, dependencies, and call graphs accurately without file-pasting.-
- AlicenseBqualityDmaintenanceEnables AI-driven semantic code search via natural language queries, integrating with MCP clients like Claude Desktop to retrieve relevant code context from any codebase.1MIT
- AlicenseAqualityDmaintenanceIndexes a mono-repo into a knowledge graph and provides MCP tools to query code structure—packages, components, routes, HTTP calls—without file reads or grep round-trips.722 npmMIT
- AlicenseNot gradedqualityBmaintenanceProvides MCP tools for Claude Code to query a project's codebase via a compact index, reducing token usage and context bloat by enabling symbol lookup, usage tracking, and dead-code detection.2 npm4MIT