# Capytail

A local MCP capability router that selects relevant skills before loading context.

Capytail is a selector, not an execution gateway. It helps agents avoid loading every skill, agent, or MCP recommendation into context up front.

## Status

Experimental `0.1.x`.

Use it when you want:

- compact capability routing;
- read-only MCP runtime tools;
- local CLI ingestion for trusted skills;
- deterministic selection before optional full skill loading.

Do not use it as:

- an MCP proxy;
- an agent orchestrator;
- persistent memory;
- a RAG/vector database;
- a remote skill installer.

## Install

```sh
npm install -g capytail
```

From source:

```sh
npm install
npm run build
node dist/src/cli.js --help
```

## MCP runtime

Start the read-only MCP server:

```sh
capytail mcp
```

Public MCP tools:

| Tool | Purpose |
|---|---|
| `capytail_route` | Select relevant capabilities for a request. |
| `capytail_list` | List compact discovered capabilities. |
| `capytail_get_capability` | Fetch full content for one selected local skill/agent id. |

Normal agent flow:

```text
capytail_route({ request })
→ capytail_get_capability({ id })
```

`route` and `list` return compact metadata only. They do not return full skill bodies.

## CLI admin

Add a local skill after a static SkillSpector scan:

```sh
capytail add-skill ./my-skill
capytail add-skill ./my-skill --project-root . --name my-skill
capytail add-skill ./my-skill --allow-medium
```

The CLI uses a fixed scanner path:

```text
$HOME/.pi/agent/tools/skillspector/.venv/bin/skillspector
```

`--skillspector-path` is intentionally rejected.

When a skill is accepted, Capytail copies it into:

```text
.capytail/skills/<name>/
```

Then it enriches the copied `SKILL.md` with missing routing metadata:

```text
aliases: <name>
triggers: ...
use_when: ...
```

It also associates the skill with the current project using the existing capability graph:

```json
{
  "graph": {
    "projectId": "project:my-project",
    "edges": [
      {
        "from": "project:my-project",
        "relation": "project_has_skill",
        "to": "skill:project:my-skill"
      }
    ]
  }
}
```

The original source skill is not modified.

## Configuration

Capytail reads `capytail.config.json` or `.capytail/config.json` from the project root.

See [`examples/capytail.config.json`](examples/capytail.config.json).

## Benchmarks

In a local corpus of 43 `SKILL.md` files:

| Flow | Approx tokens | Time |
|---|---:|---:|
| Load all skills | ~121k | n/a |
| `route` only | ~1.0k–1.3k | ~10–15ms |
| `route + get` | ~7.4k–40.8k | ~63–80ms |

See [`docs/benchmarks.md`](docs/benchmarks.md).

## Security model

See [`SECURITY.md`](SECURITY.md) and [`docs/security-model.md`](docs/security-model.md).

Short version:

- MCP surface is read-only.
- Skill ingestion is CLI-only.
- Local paths only.
- Static SkillSpector scan only, `--no-llm`.
- No remote URL ingestion.
- No dependency installation.
- No skill execution.

## Development

```sh
npm test
npm run typecheck
npm run build
```

## License

MIT