@kanchingyg/repomcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Augusto Cerrutti
+
+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

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# repomcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![ci](https://github.com/kanchingyg/repomcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kanchingyg/repomcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40kanchingyg%2Frepomcp/latest?label=npm)](https://www.npmjs.com/package/@kanchingyg/repomcp)
+[![JSR](https://jsr.io/badges/@kanchingyg/repomcp)](https://jsr.io/@kanchingyg/repomcp)
+[![JSR Score](https://jsr.io/badges/@kanchingyg/repomcp/score)](https://jsr.io/@kanchingyg/repomcp/score)
+[![Runtime](https://img.shields.io/badge/runtime-Node_%7C_Bun_%7C_Deno-f9f1e1)](https://github.com/kanchingyg/repomcp)
+[![license](https://img.shields.io/github/license/kanchingyg/repomcp)](https://github.com/kanchingyg/repomcp/blob/HEAD/LICENSE)
+
+Universal repo-to-MCP bridge: introspect a repository, expose guarded MCP tools over stdio, generate multi-harness configs (Pi, OMP, Hermes, cc-switch, Claude Code, Kilo Code, Roo Code, Cursor, Cline, OpenCode), normalize embeddings for code indexers, and adapt tool-calling for Chinese providers and raw local checkpoints.
+
+## Install
+
+[Bun](https://bun.sh) / [npm](https://www.npmjs.com/package/@kanchingyg/repomcp):
+
+```bash
+bunx @kanchingyg/repomcp init --target all
+npx @kanchingyg/repomcp init --target all
+
+# or install in your project / globally
+bun add -d @kanchingyg/repomcp
+npm i -D @kanchingyg/repomcp
+```
+
+[JSR](https://jsr.io/@kanchingyg/repomcp):
+
+```bash
+bunx jsr add @kanchingyg/repomcp
+npx jsr add @kanchingyg/repomcp
+```
+
+## Quick start
+
+```bash
+bunx @kanchingyg/repomcp init --target all
+npx @kanchingyg/repomcp --mcp
+npx @kanchingyg/repomcp embed --port 11435
+```
+
+## Architecture
+
+```text
++--------+    +-------------+    +------------------+
+|  repo  |--->| introspect  |--->| MCP tools (stdio)|
++--------+    +-------------+    +------------------+
+     |                |                    |
+     v                v                    v
++--------+    +-------------+    +------------------+
+| harness|    | dirty-parser|    | embed normalizer |
+| configs|    | checkpoints |    | (Kilo/Roo dims)  |
++--------+    +-------------+    +------------------+
+     |                |                    |
+     v                v                    v
+ Pi OMP Hermes   Chinese providers    LanceDB/Qdrant
+ Cursor Kilo     raw checkpoint EOS
+```
+
+## Flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--mcp` | Run stdio MCP server (stdout JSON-RPC guard enabled) |
+| `--allow-write` | Enable mutating tools (read-only by default) |
+| `--dry-run` | Simulate tool calls without side effects |
+
+## Programmatic API
+
+The package exports the runtime from `repomcp`, `repomcp/bridge`, and `repomcp/runtime` (also available on JSR as `@kanchingyg/repomcp`): MCP server, harness generators, provider/checkpoint helpers, dirty tool-call parser, and embedding normalizer.
+
+## MCP Tools Reference
+
+| Tool | Mutates | Description |
+| --- | --- | --- |
+| `repo_status` | `false` | Inspect repository git status, tracked languages, and detected scripts. |
+| `run_script` | `true` | Run a package.json, Cargo, or Makefile script inside the workspace (requires `--allow-write`). |
+| `search_code` | `false` | Search repository source files with context-window budget truncation. |
+
+## Editor and Agent Integration
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "repomcp": {
+      "command": "npx",
+      "args": ["-y", "@kanchingyg/repomcp", "--mcp"]
+    }
+  }
+}
+```
+
+### Claude Code CLI
+
+```bash
+claude mcp add repomcp -- npx -y @kanchingyg/repomcp --mcp
+```
+
+### Programmatic Usage (JSR / TypeScript)
+
+```ts
+import * as bridge from "jsr:@kanchingyg/repomcp/bridge";
+```
+
+## Runtime Safety and Guardrails
+
+- **Stdio frame isolation**: When `--mcp` is active, `hijackStdoutForMcp()` redirects accidental `console.log` calls to `stderr` so JSON-RPC 2.0 frames on `stdout` never corrupt.
+- **Read-only by default**: Mutating tools (`mutates: true`) are blocked in `--dry-run` mode and require explicit `--allow-write` authorization.
+- **Loop breaker**: Repeated identical `(toolName, args)` invocations are hashed with SHA-256 and halted after 3 consecutive repeats to prevent runaway agent loops.
+- **Context budget truncation**: Tool outputs are middle-truncated (`60%` head / `40%` tail) scaled to the probed local model `n_ctx` (Ollama `/api/show`, llama.cpp `/props`, vLLM `/v1/models`).
+- **Secret redaction and path normalization**: AWS keys (`AKIA*`, `ASIA*`), bearer tokens, and `sk-*` keys are scrubbed before returning tool output, and Windows drive paths (`C:\...`) translate cleanly to `/mnt/c/...` when WSL mode is enabled.
+
+## License
+
+[MIT](./LICENSE)

package/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: repomcp
+description: Turn any repo into MCP tools with multi-harness configs and model bridges.
+---
+
+# repomcp
+
+Use `npx @kanchingyg/repomcp init` to generate orchestrator-specific MCP and skill files, then run `npx @kanchingyg/repomcp --mcp` for the stdio server.
+
+For Kilo Code / Roo Code indexing issues (batch limits, dimensions, base64), run `npx @kanchingyg/repomcp embed --port 11435` and point the indexer at `http://127.0.0.1:11435/v1`.

package/dist/adapters/api-routes.d.ts

@@ -0,0 +1,31 @@
+import type { AdapterDiscovery } from "./types.js";
+export type RequestDescriptor = {
+    method: string;
+    path: string;
+    body?: unknown;
+};
+export type ApiToolResult = {
+    request: RequestDescriptor;
+    planned?: boolean;
+    status?: number;
+    responseBody?: string;
+};
+export type ApiRouteEntry = {
+    name: string;
+    method: string;
+    path: string;
+    source: "openapi" | "graphql" | "static" | "wrangler";
+    mutates: boolean;
+    description: string;
+};
+export type ApiDiscoverySummary = {
+    routeCount: number;
+    bySource: Record<string, number>;
+    byMethod: Record<string, number>;
+    routes: ApiRouteEntry[];
+};
+export declare function summarizeApiDiscovery(discovery: AdapterDiscovery): ApiDiscoverySummary;
+export declare function discoverApiRoutes(repoRoot: string, opts?: {
+    baseUrl?: string;
+}): Promise<AdapterDiscovery>;
+//# sourceMappingURL=api-routes.d.ts.map

package/dist/adapters/api-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-routes.d.ts","sourceRoot":"","sources":["../../src/adapters/api-routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAe,MAAM,YAAY,CAAC;AAEhE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB,CAAC;AAiuBF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,gBAAgB,GAAG,mBAAmB,CAuCtF;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CAiB3B"}