vitya
81af7825b6
using-interns: overview table 2→3 interns, routing hints for repo_read vs bulk_text_read, tool quick reference row. setup-interns: Phase 0 adds node --version check + optional repomix pre-warm. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
setup-interns
One-time skill that brings up the local interns MCP server on a new (or freshly broken) machine. Detects the runtime source at <project-root>/.common/lib/interns-mcp/, runs pip install -e, writes .common/secrets/interns.env with the endpoint API keys, and registers mcpServers.interns in ~/.claude.json.
The runtime policy for using the resulting tools lives in using-interns — setup-interns is the only place that touches user-level config or the project's secrets directory.
Full design (Layer 1 / 2 / 3, MVP catalog, always-ask paths, routing hints):
.wiki/concepts/interns-design.md (in this repo).
When it triggers
- User says: "install interns", "set up interns", "configure interns", "настрой интернов", "установи интернов", "interns не работает", "interns isn't working".
using-internsdetects missingmcp__interns__*tools and delegates here via its Prerequisites section.- A new machine in the multi-machine fleet — install once per machine that wants delegation.
What it touches
| Path | Role |
|---|---|
<project-root>/.common/lib/interns-mcp/ |
server source (must already exist; not created here) |
<project-root>/.common/config/interns/config.yaml |
catalog of interns + endpoints (read-only here) |
<project-root>/.common/secrets/interns.env |
endpoint API keys (gitignored) |
~/.claude.json (mcpServers.interns) |
MCP registration |
pip site-packages |
editable install of interns_mcp |
Hard rules
- Never auto-mutate. Phase 1 (discovery) and Phase 2 (plan) always pause for explicit confirmation. A trigger phrase grants permission to inspect, not to run
pip installor write secrets. - Never echo endpoint API keys in chat. Edit / Write tool calls inevitably contain them (that's how they land in
.env); chat output must not. - Never run on absent source. If
.common/lib/interns-mcp/pyproject.tomlis missing, stop and tell the user — initializing a fresh runtime is a separate task. - Always
chmod 600.envon Linux / macOS. Token leak otherwise. - Pin the absolute Python interpreter path in
mcpServers.interns.command. A barepythonresolves to whatever shadows it onPATHat session start.
Procedure (high-level)
- Phase 0 — environment sanity (
python≥ 3.11,pip, network to endpoints). - Phase 1 — discovery (source / module / config / keys / MCP registration /
.gitignore). - Phase 2 — plan + confirm. Wait for explicit "ok" / "go" / "поехали".
- Phase 3 — backup (
~/.claude.json, existing.common/secrets/interns.env). - Phase 4 —
pip install -e .common/lib/interns-mcp/. - Phase 5 — write
.common/secrets/interns.env(per-key, missing-only) + ensure.gitignorerule. - Phase 6 — register
mcpServers.internsin~/.claude.jsonwith absolute interpreter path +cwd. - Phase 7 — best-effort smoke test (in-session caveat: real verification is after restart).
- Phase 8 — restart guidance + final report.
Full procedure with shell snippets and templates lives in SKILL.md.
Rollback
- Stop. Don't fix forward.
cp <file>.bak-<ts> <file>for~/.claude.jsonand.common/secrets/interns.env.- Optional:
pip uninstall interns-mcpto undo the editable install. - Restart Claude Code.
- Confirm
mcp__interns__*tools are gone (or back to the prior version).
Install
From the repo root:
bash scripts/install.sh setup-interns
Works on Windows under git-bash, Linux, macOS.
See also
using-interns— runtime policy + per-session permission grant for themcp__interns__*tools.setup-projects-meta— companion pattern, similar 8-phase shape.setup-context7— sister setup-skill for the context7 MCP plugin.project-discipline— Rule 4 (per-session push grant) is the prior art for the grant mechanism inusing-interns..wiki/concepts/interns-design.md— full architecture spec.