tgrep-mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shizhy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE-tgrep

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/README.md

@@ -0,0 +1,283 @@
+# tgrep-mcp
+
+An MCP server that exposes [tgrep](https://github.com/microsoft/tgrep) over stdio.
+
+## Overview
+
+tgrep runs regex queries against a prebuilt trigram index instead of reading every file. This
+server exposes tgrep as MCP tools and keeps a search backend resident, so repeated queries do not
+pay process start cost.
+
+The server speaks newline-delimited JSON-RPC 2.0 on stdin and stdout. Any MCP client that can start
+a local process can run it.
+
+It provides three tools:
+
+- `tgrep_search` searches a file or directory.
+- `tgrep_index` builds or rebuilds the index for a root.
+- `tgrep_status` reports configuration, health, and counters.
+
+## Requirements
+
+- Node.js 20 or later.
+- The `tgrep` executable, version 1.0.8. The npm package does not include it. Install it from the
+  [releases page](https://github.com/microsoft/tgrep/releases) and either add it to `PATH` or set
+  `TGREP_BIN`. The git repository contains a Windows build at `bin/tgrep.exe`; the published package
+  does not.
+
+## Install and run
+
+Add the server to your MCP client configuration. This is the standard setup:
+
+```json
+{
+  "mcpServers": {
+    "tgrep": {
+      "command": "npx",
+      "args": ["-y", "tgrep-mcp"],
+      "cwd": "/path/to/your/repository"
+    }
+  }
+}
+```
+
+Two details matter:
+
+- Keep `-y` in `args`. Without it, npx prompts for confirmation, the prompt consumes stdin, and the
+  MCP handshake stalls.
+- Set `cwd` to the repository you want to search. See [Search root](#search-root).
+
+To pin a version, use `"args": ["-y", "tgrep-mcp@0.3.0"]`.
+
+To run from a checkout instead:
+
+```bash
+node /path/to/tgrep-mcp/server.mjs
+```
+
+## Configure
+
+The server reads all configuration from the environment and from the client's declared workspace
+roots. It has no built-in paths.
+
+### Search root
+
+A call to `tgrep_search` that omits `path` searches the default root. The server resolves the
+default root in this order:
+
+1. The first workspace root declared by the client, if the client supports the MCP `roots` feature.
+2. `TGREP_DEFAULT_ROOT`, if set.
+3. The working directory of the server process.
+
+Most clients do not implement `roots`. Setting `cwd` in the client configuration is therefore the
+simplest way to control the default root.
+
+### Allowed roots
+
+The server refuses to search outside the allowed roots. It resolves them in this order:
+
+1. `TGREP_ALLOWED_ROOTS`, if set. The value is a list of paths separated by `;` or `,` (POSIX
+   systems also accept `:`). The value `*` disables the check.
+2. The default root, plus any workspace roots declared by the client.
+
+Listing a directory allows everything below it. A path that is inside an allowed root is searched
+using that root's index, so a repository is indexed once even when you search a subdirectory.
+
+### tgrep executable
+
+The server resolves the executable in this order:
+
+1. `TGREP_BIN`, if set.
+2. `bin/tgrep` or `bin/tgrep.exe` next to `server.mjs`, if present. This applies to a git checkout
+   of this repository, not to an npm install.
+3. `tgrep` (or `tgrep.exe` on Windows), resolved from `PATH`.
+
+Run `tgrep_status` to see which executable and which roots are in effect.
+
+## Tools
+
+### tgrep_search
+
+Regex search over a directory or a single file.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `pattern` | string | yes | Regular expression, in ripgrep syntax. Maximum 2048 characters. |
+| `path` | string | no | File or directory to search. Absolute, or relative to the server's working directory. Defaults to the default root. Must be inside the allowed roots. |
+| `glob` | string | no | Glob filter, for example `*.ts`. Maximum 512 characters. |
+| `ignoreCase` | boolean | no | Case-insensitive matching. |
+| `maxPerFile` | integer | no | Maximum matching lines per file. |
+| `maxResults` | integer | no | Maximum matches returned. Default 200, maximum 5000. |
+| `includeGitIgnored` | boolean | no | Also search files excluded by `.gitignore`. Forces the CLI backend. |
+
+The result reports the indexed root that was searched, the resolved target, how many matches tgrep
+found, and how many were returned. Match paths are relative to that root and use forward slashes.
+
+`maxResults` bounds the match list in `structuredContent`. A second bound, `TGREP_MAX_OUTPUT_BYTES`,
+caps the total match text per call. When either bound applies, `truncated` is `true` and `warnings`
+explains which one applied.
+
+### tgrep_index
+
+Builds or rebuilds the index for a root and stops that root's search daemon. The next search starts a
+new one. The first search on an unindexed root builds the index automatically, so call this tool only
+after a branch switch, a large pull, or when results look stale.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `path` | string | no | Repository root. Defaults to the default root. |
+
+The tool indexes the outermost allowed root that contains the path.
+
+### tgrep_status
+
+Reports health, effective configuration, index freshness, and call counters. This tool reads state
+only. It does not build an index and does not start a daemon.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `path` | string | no | Root to report index and daemon detail for. Defaults to the default root. |
+
+The response contains a `status` field with the value `healthy`, `degraded`, or `unhealthy`, and a
+list of checks. Each check reports its own status, a message, and its duration. `unhealthy` takes
+precedence over `degraded`.
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `TGREP_BIN` | see [tgrep executable](#tgrep-executable) | Path to the tgrep executable. |
+| `TGREP_INDEX_ROOT` | Platform cache directory | Directory holding one index per root. On Windows, `%LOCALAPPDATA%\tgrep-mcp\index`. On macOS, `~/Library/Caches/tgrep-mcp/index`. On Linux, `$XDG_CACHE_HOME/tgrep-mcp/index` or `~/.cache/tgrep-mcp/index`. |
+| `TGREP_DEFAULT_ROOT` | Client workspace root, then working directory | Root searched when a call omits `path`. |
+| `TGREP_ALLOWED_ROOTS` | Default root plus client workspace roots | Roots that may be searched. Separated by `;` or `,`. `*` allows any path. |
+| `TGREP_TIMEOUT_MS` | `60000` | Timeout for one operation. Index builds use four times this value. |
+| `TGREP_TOOL_TIMEOUT_MS` | 4x `TGREP_TIMEOUT_MS` + 30s | Deadline for one tool call. |
+| `TGREP_DIRECT` | `auto` | Set to `off` to use the CLI backend only. |
+| `TGREP_DAEMON_WAIT_MS` | `15000` | Time to wait for a new `tgrep serve` process to become ready. |
+| `TGREP_MAX_CONCURRENCY` | `4` | Tool calls that may run at the same time, across roots. |
+| `TGREP_MAX_CALLS_PER_MINUTE` | `600` | Call budget. `0` disables it. |
+| `TGREP_MAX_RESULTS` | `5000` | Upper bound for `maxResults`. |
+| `TGREP_MAX_PER_FILE` | `10000` | Upper bound for `maxPerFile`. |
+| `TGREP_MAX_LINE_CHARS` | `512` | Maximum length of the text of one match. |
+| `TGREP_MAX_OUTPUT_BYTES` | `262144` | Maximum total match text returned by one call. |
+| `TGREP_INDEX_STALE_MS` | `86400000` | Index age that produces a staleness warning. |
+| `TGREP_LOG_LEVEL` | `normal` | `quiet`, `normal`, or `debug`. Diagnostics go to stderr. |
+
+A value that cannot be parsed does not stop the server. The server logs the problem, uses the
+default, and reports it in the `configuration` check of `tgrep_status`.
+
+## Index location and freshness
+
+Each root has one index directory under `TGREP_INDEX_ROOT`. The directory name contains a readable
+part derived from the root and a hash of the full path, so two roots can never share an index.
+
+Indexes are written outside the searched repository. Searching a repository does not modify it.
+
+With the direct backend, a resident `tgrep serve` process watches for changes and keeps the index
+current. Otherwise the index reflects the last build. `tgrep_status` reports the index age, and
+`tgrep_search` adds a warning when the index is older than `TGREP_INDEX_STALE_MS`.
+
+To delete all indexes, remove the directory named by `TGREP_INDEX_ROOT`. They are rebuilt on demand.
+
+## Search backends
+
+The server tries two backends in order.
+
+1. **direct.** A TCP JSON-RPC connection to a resident `tgrep serve` process. The server starts that
+   process if needed, and reuses a healthy one that is already running. Ports are advertised in
+   `serve.json` inside the index directory. This backend avoids creating a process per search and
+   avoids re-reading the index.
+
+2. **cli.** A `tgrep` child process per search. This backend is slower and is the fallback.
+
+The direct protocol is not a documented tgrep interface. The server records the tgrep release it was
+verified against and reports a `degraded` status when the installed release differs. Any connection
+or protocol error falls back to the CLI backend. After three consecutive direct failures the server
+pauses the direct backend for 30 seconds, doubling the pause on each further failure up to five
+minutes.
+
+The server stops daemons it started when it exits, and removes their `serve.json`. It never stops a
+daemon it did not start.
+
+### Performance
+
+The figures below were measured on the development machine with a repository of moderate size. They
+are indicative only; absolute values depend on the machine and the size of the index.
+
+| Query | direct | cli |
+|---|---|---|
+| No matches | ~6 ms | ~200 ms |
+| 4 matches | ~9 ms | ~200 ms |
+| 1613 matches, cold cache | ~198 ms | ~500 ms |
+
+The first search on a root adds the cost of starting a daemon and building an index.
+
+## Ignore rules
+
+tgrep does not apply ripgrep's `.ignore` re-include rules. If a repository's `.ignore` re-includes a
+tree that `.gitignore` excludes, tgrep skips those files and ripgrep does not. An empty result can
+therefore be wrong for such a repository.
+
+When an empty result is the conclusion, confirm it with a tool that follows ripgrep semantics. To
+include gitignored files in a tgrep search, set `includeGitIgnored`. That forces the CLI backend.
+
+## Security and limits
+
+- Every argument is validated for type, range, and length. Unknown arguments are rejected.
+- Searches are confined to the allowed roots. Path containment is evaluated per path segment, and
+  paths on another volume are rejected.
+- Calls are limited to `TGREP_MAX_CALLS_PER_MINUTE` by default. A rejected call returns
+  `RATE_LIMITED` with a retry delay.
+- Match text is stripped of control characters and truncated to `TGREP_MAX_LINE_CHARS`. Result sets
+  are bounded by `maxResults` and `TGREP_MAX_OUTPUT_BYTES`.
+- Each call writes one audit record to stderr.
+
+Failures return a stable `error.code`. The codes are `VALIDATION_ERROR`, `PATH_NOT_ALLOWED`,
+`NOT_FOUND`, `BINARY_MISSING`, `INDEX_FAILED`, `BACKEND_UNAVAILABLE`, `TIMEOUT`, `CANCELLED`,
+`RATE_LIMITED`, and `INTERNAL_ERROR`. `RATE_LIMITED` and `TIMEOUT` include `retryAfterSeconds`.
+`PATH_NOT_ALLOWED` requires a different path or a configuration change, not a retry.
+
+Invalid arguments are reported as JSON-RPC errors with code `-32602`. Failures during execution are
+reported as tool results with `isError: true` and a structured error object.
+
+## Troubleshooting
+
+**The tools do not appear in the client.** Run `npx -y tgrep-mcp` in a terminal. The process should
+start and wait for input. If it exits, read the error on stderr.
+
+**`BINARY_MISSING`.** The server could not start tgrep. Install tgrep, or set `TGREP_BIN` to its full
+path. Run `tgrep_status` to see the path the server resolved.
+
+**`PATH_NOT_ALLOWED`.** The requested path is outside the allowed roots. Add the path to
+`TGREP_ALLOWED_ROOTS`, set that variable to `*`, or set `cwd` to a directory that contains it.
+
+**`TIMEOUT`.** The query exceeded `TGREP_TIMEOUT_MS`. Narrow the pattern, add a `glob`, or search a
+subdirectory.
+
+**A search returns fewer files than ripgrep.** See [Ignore rules](#ignore-rules).
+
+**`tgrep_status` reports `degraded`.** Read the `checks` array. Common causes are a missing index
+(the first search builds one), an unreachable daemon (searches will use the CLI backend), and a
+tgrep release other than the verified one.
+
+## Development
+
+```bash
+npm test        # unit tests, no process spawning required
+npm run probe   # end-to-end protocol and conformance check
+```
+
+The probe starts a server and exercises every tool, including the failure paths. It requires the
+ability to spawn a process with piped stdio. It validates the responses against the schemas the
+server advertises. Set `TGREP_PROBE_SERVER` to test an installed copy of the package instead of the
+working tree.
+
+The probe reports round-trip time per call. Measurements from a single run are not meaningful on a
+loaded machine; compare repeated runs.
+
+## License
+
+MIT. See `LICENSE`.
+
+The git repository distributes a tgrep binary, which is also MIT licensed. See `LICENSE-tgrep`. The
+npm package does not include that binary.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "tgrep-mcp",
+  "version": "0.3.0",
+  "description": "MCP server that exposes tgrep, a trigram-indexed regex search tool, over stdio.",
+  "license": "MIT",
+  "author": "Shizhy <usstpeter@163.com>",
+  "type": "module",
+  "bin": {
+    "tgrep-mcp": "server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "README.md",
+    "LICENSE",
+    "LICENSE-tgrep"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "tgrep",
+    "grep",
+    "regex",
+    "code-search",
+    "stdio"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node test/server.test.mjs",
+    "probe": "node probe.mjs",
+    "prepack": "node test/server.test.mjs"
+  }
+}