代码搜索 MCP 服务

text-search-mcp

Read-only code search over Model Context Protocol (stdio) — backed by ripgrep (rg) with an optional GNU grep fallback. Hosts (IDEs, agents, scripts) get validated, schema-versioned JSON instead of ad-hoc shell pipelines.

Docs: Documentation index · User guide · Examples · Troubleshooting · Architecture · Contributing · CHANGELOG

Reference: Client contract (schema v1 + errors) · Security · Deployment · Releasing · ADRs · Code of Conduct · Generated tool JSON Schema

Installation

Requirements: Node.js ≥ 20.11 · rg strongly recommended on PATH · if the backend resolves to grep, GNU grep must be detected (grep --version).

From a checkout or published package:

npm install
npm run build

Global or monorepo usage after build:

npm link   # optional: makes `text-search-mcp` available on PATH

The text-search-mcp binary is declared in package.json (bin → dist/index.js). Set TEXT_SEARCH_MCP_ALLOWED_ROOTS (or TEXT_SEARCH_MCP_CONFIG) before clients connect; RG_MCP_* variables remain supported as legacy aliases. Full env tables and behavior: docs/user-guide.md.

Connecting an MCP client (stdio)

The server speaks MCP over stdin/stdout. Configure the host with a command, optional args, and environment (at minimum TEXT_SEARCH_MCP_ALLOWED_ROOTS for real workspaces).

Example — local checkout (use absolute paths on your machine):

{
  "mcpServers": {
    "text-search-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/text-search-mcp/dist/index.js"],
      "env": {
        "TEXT_SEARCH_MCP_ALLOWED_ROOTS": "/absolute/path/to/repo"
      }
    }
  }
}

• Cursor: merge the text-search-mcp entry into mcpServers in Cursor MCP settings (user or project).
• Other hosts: same idea — command + args + env; avoid unnecessary shell wrappers so arguments are not re-parsed.

Prefer npm run build so dist/index.js exists. After changing roots or upgrading the server, restart the MCP session so the host spawns a new process. More tool examples and response shapes: docs/examples.md.

Learn more

License

Apache License 2.0. See LICENSE and NOTICE.