diff --git a/README.md b/README.md index 7617b4e..f807d65 100644 --- a/README.md +++ b/README.md @@ -155,22 +155,25 @@ The first local `llama.cpp` run may download the default embedding model, fetch Each provider and model pair keeps its own active index snapshot. Rebuilding `openrouter/openai/text-embedding-3-small` does not replace the active `llama.cpp/embeddinggemma` snapshot until the new run finishes successfully. -## MCP +## MCP for Codex -`unch` can run as a stdio MCP server for agents and editors: +The recommended MCP setup is through the npm wrapper: ```bash -unch start mcp +npm install -g @uchebnick/unch +unch codex install ``` -Configure MCP clients with command `unch`, arguments `start mcp`, and working directory set to the repository you want to search. +Then restart Codex. The setup command registers the `unch` MCP server and installs the `unch` skill in `~/.codex/skills/unch/SKILL.md`. -The server exposes: +After restart, ask Codex a codebase question as usual. The skill tells Codex to use these MCP tools before broad file reads: - `workspace_status` to inspect the repository root, state directory, active provider/model, and index status - `search_code` to search indexed code symbols before opening many files - `index_repository` to build or refresh the index when needed +Codex starts the stdio server for you with `unch start mcp`; you normally do not need to run that command by hand. + ## What It Supports Today - Tree-sitter indexing for `Go`, `Rust`, `TypeScript`, `JavaScript`, and `Python` diff --git a/SECURITY.md b/SECURITY.md index 0317a46..562f8a0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,7 +7,7 @@ latest stable release line and the current `main` branch. | Version | Supported | | --- | --- | -| `v0.3.x` | Yes | +| `v0.4.x` | Yes | | older releases | No | | `main` | Best effort | @@ -51,4 +51,3 @@ This policy covers: Third-party services, GitHub-hosted infrastructure, and vulnerabilities in upstream dependencies may need to be reported upstream as well. - diff --git a/mintlify/commands.mdx b/mintlify/commands.mdx index 5f86899..d905a3c 100644 --- a/mintlify/commands.mdx +++ b/mintlify/commands.mdx @@ -69,10 +69,11 @@ unch remote sync Use the command pages for the full flag reference and behavior notes. -## Typical MCP flow +## Typical MCP flow for Codex ```bash -unch start mcp +npm install -g @uchebnick/unch +unch codex install ``` -Configure your MCP client with command `unch`, arguments `start mcp`, and working directory set to the repository root. +Restart Codex after installation. Codex will start `unch start mcp` automatically through the registered MCP server and use the installed `unch` skill when code search helps. diff --git a/mintlify/commands/mcp.mdx b/mintlify/commands/mcp.mdx index 75d14b1..b34d60c 100644 --- a/mintlify/commands/mcp.mdx +++ b/mintlify/commands/mcp.mdx @@ -1,36 +1,31 @@ --- title: MCP -description: Start the unch stdio MCP server for agents and editor integrations. +description: Install and use unch MCP from Codex. --- -## Usage +## Codex setup -```bash -unch start mcp [flags] -``` - -From the repository root, the common case is: +Install the npm wrapper and register unch with Codex: ```bash -unch start mcp +npm install -g @uchebnick/unch +unch codex install ``` -MCP uses stdio, so stdout is reserved for protocol messages. Run this command as a child process from an MCP client rather than as an interactive terminal command. +Then restart Codex. -## Client configuration +`unch codex install` does two things: -Use: +- registers the `unch` MCP server with Codex +- writes the `unch` skill to `~/.codex/skills/unch/SKILL.md` -- Name: `unch` -- Command: `unch` -- Arguments: `start`, `mcp` -- Working directory: the repository you want to search +The npm `postinstall` step does not modify Codex automatically. Run `unch codex install` explicitly when you want the integration. + +## How to use it -The server uses: +After restarting Codex, work in a repository and ask codebase questions normally. The installed skill tells Codex to call unch before broad file reads when semantic code search can help. -- root: current working directory -- state dir: `/.semsearch` -- provider/model: the same defaults as the CLI +Codex starts the stdio MCP server for you. You normally do not need to run `unch start mcp` by hand. ## Tools @@ -52,51 +47,19 @@ Builds or refreshes the index for the configured workspace. Agents should call this when no index exists, when search reports no active snapshot for the selected provider/model, or when the user explicitly asks to rebuild. -## Flags - -### `--root` - -Repository root served by the MCP process. Defaults to `.`. - -### `--state-dir` - -Path to a custom `.semsearch` directory. Defaults to `/.semsearch`. - -### `--model` - -Embedding model to use. Accepts `embeddinggemma`, `qwen3`, a `.gguf` path, or an OpenRouter model id when `--provider openrouter` is selected. +## What Codex runs -### `--provider` +The registered MCP server uses: -Embedding provider. Accepted values: - -- `llama.cpp` -- `openrouter` - -### `--lib` - -Path to a `yzma` library directory, or one of its shared library files. - -### `--ctx-size` - -llama context size. `0` uses the selected model default. - -### `--verbose` - -Enable verbose `yzma` logging. - -## Examples +- Name: `unch` +- Command: `unch-mcp` +- Arguments: none -```bash -unch start mcp -unch start mcp --root ~/src/repo --state-dir ~/src/repo/.semsearch -unch start mcp --root . --model qwen3 -unch start mcp --provider openrouter --model openai/text-embedding-3-small -``` +`unch-mcp` is a small launcher for `unch start mcp`. ## Notes -- Use one MCP process per repository workspace. +- The installed skill passes the active repository directory into unch MCP tool calls. - The process reuses the same provider/model/runtime configuration across tool calls. - OpenRouter token lookup checks `OPENROUTER_API_KEY`, then `~/.config/unch/tokens.json`, then `.semsearch/tokens.json`. - The MCP server exposes tools only in this release; streamable HTTP is not supported yet. diff --git a/npm/unch/README.md b/npm/unch/README.md index 18f446d..6c79fe0 100644 --- a/npm/unch/README.md +++ b/npm/unch/README.md @@ -22,18 +22,17 @@ Then restart Codex. The installer uses `codex mcp add` for the MCP server and wr The npm `postinstall` step does not modify your Codex config automatically. This is intentional: installing a package should not silently mutate `~/.codex/config.toml`. -## MCP +## MCP for Codex -For MCP clients, use: +Codex setup is explicit: -- Name: `unch` -- Command: `unch-mcp` -- Arguments: leave empty -- Working directory: the repository you want to search +```bash +unch codex install +``` -`unch-mcp` is a small launcher for `unch start mcp`. +Then restart Codex. Codex will start the MCP server through the registered `unch-mcp` command and use the installed `unch` skill when semantic code search helps. -For Codex CLI specifically, `unch codex install` also creates a local reusable skill, so Codex knows when to call `workspace_status`, `search_code`, and `index_repository` in the right order. +`unch-mcp` is a small launcher for `unch start mcp`; you normally do not need to run it by hand. Supported targets: