Metadata-Version: 2.4
Name: maki-mcp
Version: 0.2.1
Summary: Run dev commands and expose their logs over MCP.
Requires-Python: >=3.13
Requires-Dist: mcp>=1.28.1
Requires-Dist: rich>=15.0.0
Description-Content-Type: text/markdown

# maki

Run a dev command, save its terminal output per project, and let MCP-capable agents read the logs without copy/paste.

```bash
maki --name dev pnpm dev
```

Then ask your agent:

> Check the maki dev logs and fix the error.

## How it works

```text
maki --name dev pnpm dev
  ├─ runs pnpm dev
  ├─ prints output to your terminal
  └─ writes logs to .maki/runs/<run-id>.log

maki-mcp --project /path/to/project
  └─ exposes MCP tools that read .maki logs
```

Each run gets:

```text
.maki/
  active.json
  runs/
    20260710-090000-a1b2c3.log
    20260710-090000-a1b2c3.json
```

The run id is timestamp + random suffix. `--name` is the human label agents can use, like `dev`, `api`, `web`, or `worker`.

## Install

Recommended:

```bash
pipx install maki-mcp
```

or:

```bash
uv tool install maki-mcp
```

On Windows without pipx:

```powershell
py -m pip install --user pipx
py -m pipx ensurepath
pipx install maki-mcp
```

Avoid system-wide `pip install maki-mcp`. Some Python installs, like Homebrew Python, block it with an "externally managed environment" error. `pipx`/`uv tool` install maki as a CLI without touching system Python.

Maki works in any project, not just Python projects:

```bash
cd my-node-app
maki --name dev pnpm dev
```

The package is `maki-mcp`, but the commands are:

```bash
maki
maki-mcp
```

## Usage

Start your app through maki:

```bash
maki --name dev pnpm dev
maki --name api npm run api
maki --name worker python worker.py
```

If you omit `--name`, it defaults to `dev`:

```bash
maki pnpm dev
```

Start the MCP server for that project:

```bash
maki-mcp --project /path/to/project
```

MCP tools:

- `list_runs()`
- `latest_logs(name="dev", lines=200)`
- `get_log(run_id="...", lines=200)`

## MCP config

Use stdio transport. No port needed.

### Claude Code

CLI:

```bash
claude mcp add maki -- maki-mcp --project /path/to/project
```

Config shape:

```json
{
  "mcpServers": {
    "maki": {
      "command": "maki-mcp",
      "args": ["--project", "/path/to/project"]
    }
  }
}
```

### Codex

`~/.codex/config.toml`:

```toml
[mcp_servers.maki]
command = "maki-mcp"
args = ["--project", "/path/to/project"]
```

Or with the CLI:

```bash
codex mcp add maki -- maki-mcp --project /path/to/project
```

### Antigravity / `agy`

`~/.gemini/config/mcp_config.json`:

```json
{
  "mcpServers": {
    "maki": {
      "command": "maki-mcp",
      "args": ["--project", "/path/to/project"]
    }
  }
}
```

### Pi

Pi does not ship built-in MCP support, so maki ships a Pi package that registers equivalent Pi tools.

Install from GitHub:

```bash
pi install git:github.com/mr-jones123/maki
```

Or test from a local checkout:

```bash
pi -e /path/to/maki
```

Pi tools exposed:

- `maki_list_runs()`
- `maki_latest_logs(name="dev", lines=200)`
- `maki_get_log(run_id="...", lines=200)`

Ask:

```text
Use maki_latest_logs for dev and inspect the error.
```

## Publishing

Use Conventional Commits:

```text
fix: patch release
feat: minor release
feat!: major release
```

Merges to `main` are versioned by Python Semantic Release and published to PyPI by GitHub Actions.
