# codex-local-ollama-mcp

[中文说明](README_zh-CN.md)

`codex-local-ollama-mcp` adds one deliberately narrow MCP tool, `local_text`,
to Codex. It asks a local Ollama instance to draft a transformation of text
that you supplied. Codex remains the planner and must review the resulting
draft before replying.

This is a GitHub-only project release. The package is private and is not
published to npm.

## Capability boundary

The server exposes exactly one stdio MCP tool and accepts exactly one local
model: `qwen3.5:9b` at `http://127.0.0.1:11434`. It only supports
self-contained, read-only transformations of user-provided text:

- `translate`
- `summarize`
- `rewrite`
- `extract`
- `classify`

It does not execute commands, access files, write files, make Git changes,
browse the web, use non-loopback network endpoints, receive tool definitions,
or make decisions. Do not use it for current facts, code or operational work,
or financial, medical, legal, security-sensitive, or other high-stakes work.
Use Codex's normal tools for exact calculations and deterministic work.

The output is labeled `Local draft` with its model and mode. Treat it as a
draft, not verified information.

For these simple draft transformations, the server deliberately sends the
fixed Ollama request option `think: false` to disable qwen3.5 thinking and
reduce latency. This is server-side only: callers cannot configure it, and it
does not broaden the capability or safety boundaries. It is not a latency
guarantee.

## Requirements

- Node.js 22 or newer
- [Ollama](https://ollama.com/) available on `PATH`
- The exact local model `qwen3.5:9b`
- The Codex CLI on `PATH`; it registers the server used by Codex desktop or
  the CLI
- Codex desktop if you want to use the desktop interface

Keep Ollama bound to its local loopback default. Do not expose Ollama on your
LAN or the public internet for this integration.

## Install

Clone this repository, then fetch the required model:

```sh
git clone https://github.com/kisara174/codex-local-ollama-mcp.git
cd codex-local-ollama-mcp
ollama pull qwen3.5:9b
ollama list
node --version
codex --version
./install.sh
```

`install.sh` checks Node, Ollama, the exact model, and the local `codex`
command. It then runs `npm ci`, builds the server, and registers it as
`local-ollama` with the local Codex CLI. It refuses to overwrite an existing
registration of that name.

For desktop use, fully restart the Codex desktop app after installation. Then
verify that `local-ollama` is connected in **Settings → MCP Servers** or type
`/mcp` in Codex. CLI users can also inspect the registration with:

```sh
codex mcp get local-ollama
```

## Using `local_text`

Ask Codex for a bounded transformation of text you include in your request.
It may call the tool with this schema:

```text
mode: translate | summarize | rewrite | extract | classify
input: required text, up to 12,000 characters
instruction: optional short formatting preference, up to 500 characters
```

The instruction is intentionally restrictive: use a simple output or
formatting preference. These examples are accepted by the current validator:

```text
mode: translate
input: Good morning.
instruction: Translate to Chinese and preserve formatting.

mode: summarize
input: <text you provide>
instruction: Use two bullet points.

mode: rewrite
input: <text you provide>
instruction: Use a professional tone.

mode: extract
input: <text you provide>
instruction: Return a JSON list.

mode: classify
input: Category choices: billing, technical, account. Text: I cannot sign in.
instruction: Return one line only.
```

Put category choices and extraction criteria in the supplied input when the
instruction cannot express them as a formatting preference. The service
rejects blank or oversized input, unsupported modes, oversized instructions,
and instructions that are not accepted as short formatting/output preferences.

## Errors and troubleshooting

Tool errors start with one of these codes:

- `INVALID_REQUEST`: Use a supported mode, non-blank input within the limit,
  and a short formatting preference.
- `OLLAMA_UNAVAILABLE`: Start Ollama locally and confirm it remains reachable
  at its loopback default (`127.0.0.1:11434`). Do not solve this by exposing it
  to a LAN.
- `MODEL_UNAVAILABLE`: Run `ollama pull qwen3.5:9b`, then confirm the exact
  name appears in `ollama list`.
- `OLLAMA_TIMEOUT`: The local request has a 60-second bounded timeout. Retry a
  smaller transformation after checking that the local machine is not
  overloaded; the bound does not promise that every request will finish within
  60 seconds.
- `OLLAMA_BAD_RESPONSE`: Restart the local Ollama service and retry. If it
  persists, inspect the local service logs without sharing sensitive data.

If installation reports an existing `local-ollama` registration, remove it
only if it is the registration you intend to replace:

```sh
./uninstall.sh
./install.sh
```

## Privacy and limits

The server sends only the text passed to `local_text` to the local Ollama
HTTP endpoint on loopback. It does not send that request to a remote endpoint.
The cloud Codex agent still sees the request and local draft in order to route,
inspect, and answer, so this tool is not an end-to-end privacy boundary.

Using a local drafting step does not guarantee a reduction in cloud Codex or
ChatGPT quota usage. The cloud agent still decides whether to call the tool
and reviews the result.

## Uninstall

From this checkout, run:

```sh
./uninstall.sh
```

It first checks that the `local-ollama` MCP registration runs exactly
`node <this-checkout>/dist/index.js`, then removes that registration and this
checkout's generated `dist` and `node_modules` directories. A missing,
mismatched, or unreadable registration leaves the registration and generated
files untouched. It does not remove Ollama, the model, or unrelated Codex settings.

## Roadmap

After the v0.1.0 release has been observed in real use, the planned next phase
is a separate evaluation corpus and runner for fixed local-text tasks. Its
results will be reviewed before considering any broader local-model authority.