# ipython2-mcp

This project allows an agent to run Python 2 IPython sessions via an MCP.

The MCP server is written in TypeScript. Each session is a Python 2 broker process owning one
IPython kernel process, driven over JSON-RPC on stdio.

## Tools

| tool | params | what it does |
| --- | --- | --- |
| `ipython_install_deps` | `python_path`, `timeout_ms?` | pip-installs the kernel dependencies into a Python 2.7 interpreter |
| `ipython_start` | `name`, `python_path`, `cwd?`, `env?` | starts a named session on the given Python 2.7 interpreter |
| `ipython_stop` | `name`, `timeout_ms?` | stops a session and frees the name |
| `ipython_status` | — | one line per live session |
| `ipython_run` | `name`, `code`, `timeout_ms?` | runs code, returns the transcript |
| `ipython_complete` | `name`, `prefix` | tab completion |

Introspection, namespace listing, and history go through IPython itself (`var?`, `var??`,
`%whos`, `%history`) rather than dedicated tools.

## Setup

Install and build the server:

```
npm install
npm run build
```

That produces `dist/ipython2-mcp.js` — a single self-contained file. Register it with your MCP
client as `node <repo>/dist/ipython2-mcp.js`.

The repo's `.mcp.json` already does that with a path relative to the repo root, so an MCP client
started there picks the server up with no further configuration. Run `npm run build` first:
`dist/` is not committed.

To distribute, ship `dist/ipython2-mcp.js` together with the `python/` directory beside it — those
scripts are run by the user's Python 2 interpreter, so they cannot be bundled into the JS.

Then point `python_path` at any Python 2.7 interpreter — a venv's interpreter is the intended use.
It needs the kernel dependencies, which the agent can install for itself with
`ipython_install_deps`, or you can do by hand:

```
<py2>/python -m pip install -r python/requirements.txt
```

No kernelspec registration is needed; the kernel is launched with that interpreter directly.

`SKILL.md` is an agent-facing guide to working in the session; install it into `.claude/skills/`
if you want your agent to have it.

## Distribution

`dist/ipython2-mcp.js` is **committed**, so users need nothing but node — no npm install, no
TypeScript toolchain. Two things ship: that file and the `python/` directory beside it. Everything
else in the repo is development-only.

If you change `src/`, rebuild and commit the bundle in the same commit:

```
npm run build          # tsc -> build/, esbuild -> dist/ipython2-mcp.js
npm run check:bundle   # fails if the committed bundle is stale; wire into CI
```

`python/` must remain a sibling of `dist/` — the server resolves the broker relative to its own
location. See [ARCHITECTURE.md](ARCHITECTURE.md) for the plugin layout and `.mcp.json` snippet.

## Tests

```
npm test                                                   # TypeScript
<py2>/python -m pip install -r python/requirements-dev.txt
<py2>/python -m pytest python/tests                        # broker, against a real kernel
PYTHON2=<py2>/python npm run test:e2e                      # smoke, needs a build first
```

See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design and the reasoning behind it.