From 54ba5caf5a2348f7b967ea6760dabc4ae339dcec Mon Sep 17 00:00:00 2001 From: vitya Date: Thu, 7 May 2026 13:17:57 +0300 Subject: [PATCH] fix(setup-interns): absolute paths + gitea clone fallback [v0.3.0] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace all `/.common/...` with `~/projects/.common/...` (POSIX-absolute paths, mirroring setup-projects-meta after the using-projects-meta-fix-paths fix). The cwd-relative form broke when Claude was launched from System32 or another non-project dir. - Add git clone fallback: when `interns-mcp` source is absent, clone from `https://git.kzntsv.site/OpeItcLoc03/interns-mcp` instead of stopping with "initialize first". Mirrors setup-projects-meta Phase 4. - Remove "source must be in place" from Out of scope (now handled). - Fix MCP registration cwd to `~/projects` (base dir containing .common/). - Bump version 0.2.0 → 0.3.0 (MINOR — new capability: clone fallback). Closes [setup-interns-fix-paths] + [setup-interns-clone-fallback]. Co-Authored-By: Claude Opus 4.7 --- dist/setup-interns.skill | Bin 7846 -> 8091 bytes skills/setup-interns/SKILL.md | 94 +++++++++++++++++++++------------- 2 files changed, 58 insertions(+), 36 deletions(-) diff --git a/dist/setup-interns.skill b/dist/setup-interns.skill index f036a273e9e405fa69971939cac4ef55df52ad48..669855cf45bba2b63b8644c6eaf7c37d307cabc3 100644 GIT binary patch delta 6010 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/.common/lib/interns-mcp/` that delegates bulk reads, transcript distillation, and other predictable I/O to cheap intern LLMs (DeepSeek / Kimi / Ollama) so Claude saves Anthropic quota. Procedure: detect the server source, `pip install -e` it, write `.common/secrets/interns.env` with the endpoint API keys, register `mcpServers.interns` in `~/.claude.json`. Use this skill when the user says "install interns", "set up interns", "configure interns", "настрой интернов", "установи интернов", "interns не работает", "interns isn't working", or whenever the `mcp__interns__*` tools are missing in a session that needs delegation. Cross-platform — Windows / Linux / macOS. Mutates user-level config and writes secrets; pauses for confirmation before every write. +version: 0.3.0 +description: Installs and configures the local `interns` MCP server — clones the repo to `~/projects/.common/lib/interns-mcp/` (or uses an existing clone), `pip install -e` it, writes `~/projects/.common/secrets/interns.env` with endpoint API keys, and registers `mcpServers.interns` in `~/.claude.json`. Use this skill when the user says "install interns", "set up interns", "configure interns", "настрой интернов", "установи интернов", "interns не работает", "interns isn't working", or whenever the `mcp__interns__*` tools are missing in a session that needs delegation. Cross-platform — Windows / Linux / macOS. Mutates user-level config and writes secrets; pauses for confirmation before every write. --- # setup-interns @@ -19,15 +19,14 @@ Reference: full design lives in this repo at `.wiki/concepts/interns-design.md` ## Out of scope -- Building or scaffolding the `.common/lib/interns-mcp/` source tree itself. The skill expects the source already in place per the inline `.common/` convention from the design (or a future Gitea repo when that branch lands). If the source is absent, Phase 1 stops with a clear message — initializing a fresh runtime is a separate task. - Issuing or rotating endpoint API keys (Ollama Cloud, OpenRouter, etc.). The skill *uses* keys the user already has; if there is none, it points at the provider's settings page and stops. - Running `interns-mcp` itself — the Claude Code harness spawns it on session start. -- Authoring new interns or editing `.common/config/interns/config.yaml` — that's a content task, not a setup task. +- Authoring new interns or editing `~/projects/.common/config/interns/config.yaml` — that's a content task, not a setup task. - Any other MCP server. ## Hard rule: don't auto-mutate config -The procedure runs `pip install`, writes `.common/secrets/interns.env` (carries endpoint API keys), and edits `~/.claude.json`. **Always pause for explicit confirmation between Phase 1 (discovery, read-only) and Phase 2 (plan), and again before Phase 3 (backup + writes).** A trigger phrase grants permission to inspect, not to install or write secrets. +The procedure runs `pip install`, writes `~/projects/.common/secrets/interns.env` (carries endpoint API keys), and edits `~/.claude.json`. **Always pause for explicit confirmation between Phase 1 (discovery, read-only) and Phase 2 (plan), and again before Phase 3 (backup + writes).** A trigger phrase grants permission to inspect, not to install or write secrets. ## Procedure @@ -38,28 +37,36 @@ The procedure runs `pip install`, writes `.common/secrets/interns.env` (carries - Confirm `node` is on `PATH` (`node --version`). The `repo_read` intern runs `npx repomix@latest` as a subprocess. If `node` is absent, the user must install Node.js 20+ before proceeding — `repo_read` calls will fail at runtime with a clear "node not found" error. - (Optional, recommended) Pre-warm the repomix binary: `npx --yes repomix@latest --version`. This caches the package so the first real `repo_read` call is instant (5–10s first-run penalty avoided). Skip silently on failure — the call will just be slower the first time. - Confirm network reachability to the configured endpoints (default: `https://ollama.com/v1`). On HTTP 401 / 403 later, the API key is dead — stop and ask for a new one. -- Pick paths: `/.common/lib/interns-mcp/` (source), `/.common/config/interns/config.yaml` (catalog), `/.common/secrets/interns.env` (keys, gitignored), `~/.claude.json` (MCP registration). POSIX-style paths resolve correctly under git-bash on Windows. +- Confirm `git` is on `PATH` (needed for clone-fallback in Phase 4 if the source isn't already present). +- Pick paths: `~/projects/.common/lib/interns-mcp/` (source), `~/projects/.common/config/interns/config.yaml` (catalog), `~/projects/.common/secrets/interns.env` (keys, gitignored), `~/.claude.json` (MCP registration). POSIX-style paths resolve correctly under git-bash on Windows. ### Phase 1 — Discovery (read-only) Search, in order. Report only "found at ", never echo key values. -**Server source.** Check whether `/.common/lib/interns-mcp/pyproject.toml` exists. If absent, **stop** — the runtime source must be in place before this skill runs. Report: +**Server source.** Check whether `~/projects/.common/lib/interns-mcp/pyproject.toml` exists. + +- If present → report "found at ~/projects/.common/lib/interns-mcp/". Phase 4 will `pip install -e` (or skip if already importable). +- If absent → report "source not found — will clone from gitea". Phase 4 will `git clone https://git.kzntsv.site/OpeItcLoc03/interns-mcp ~/projects/.common/lib/interns-mcp` then `pip install -e`. + +If `git clone` fails (no network, no Gitea PAT, repo doesn't exist yet), stop with a clear message: ``` -.common/lib/interns-mcp/ not found. -This skill expects the inline interns-mcp source per the -.common/ layout (see .wiki/concepts/interns-design.md). Initialize -the runtime first, then re-run setup-interns. +Failed to clone interns-mcp source. Options: +1. Check network access to https://git.kzntsv.site +2. If you need a Gitea PAT: https://git.kzntsv.site/user/settings/applications + (scope: read:repository is sufficient) +3. If the repo doesn't exist yet on Gitea, initialize it manually + and re-run setup-interns. ``` -**Build artifact.** Run `python -c "import interns_mcp" 2>&1` against the candidate interpreter. If it fails with `ModuleNotFoundError`, Phase 4 will run `pip install -e .common/lib/interns-mcp/`. If it succeeds, capture the installed location and skip the install in Phase 4. +**Build artifact.** Run `python -c "import interns_mcp" 2>&1` against the candidate interpreter. If it fails with `ModuleNotFoundError`, Phase 4 will run `pip install -e ~/projects/.common/lib/interns-mcp/`. If it succeeds, capture the installed location and skip the install in Phase 4. -**Config catalog.** Read `/.common/config/interns/config.yaml`. Extract the unique set of `endpoints..api_key_env` values — these are the env var names the runtime expects to find. Capture for Phase 2. +**Config catalog.** Read `~/projects/.common/config/interns/config.yaml`. Extract the unique set of `endpoints..api_key_env` values — these are the env var names the runtime expects to find. Capture for Phase 2. **Existing endpoint keys.** Look in priority order, per `api_key_env` name from the config: -1. `/.common/secrets/interns.env` (`=...` lines). +1. `~/projects/.common/secrets/interns.env` (`=...` lines). 2. Process env (`os.environ[]`). 3. `~/.config/projects-mcp/auth.toml` — only if the user has explicitly noted the key is shared with another local MCP server (rare). @@ -67,20 +74,20 @@ The first hit wins per key. **Never echo key values in chat.** **MCP registration.** Read `~/.claude.json` and check `mcpServers.interns`. Note the `command` and `args`. If args point at a stale interpreter, Phase 6 will fix it. -**Gitignore sanity.** Check `.gitignore` (project root). If `.common/secrets/` (or `.common/secrets/*.env`) is not listed, flag for Phase 2 — the skill will offer to add it before writing the file. +**Gitignore sanity.** Check `~/projects/.gitignore`. If `.common/secrets/` (or `.common/secrets/*.env`) is not listed, flag for Phase 2 — the skill will offer to add it before writing the file. ### Phase 2 — Plan + confirm Present a single-block plan to the user: ``` -Source: +Source: Module: -Config: — endpoints: +Config: — endpoints: Missing keys: not yet present in interns.env | none> Gitignore: MCP entry: -Backups: ~/.claude.json.bak-, .common/secrets/interns.env.bak- (if exists) +Backups: ~/.claude.json.bak-, ~/projects/.common/secrets/interns.env.bak- (if exists) ``` Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop. @@ -94,16 +101,28 @@ Copy each file we will modify to `.bak-YYYYMMDD-HHMMSS`: ```bash TS=$(date +%Y%m%d-%H%M%S) [ -f ~/.claude.json ] && cp ~/.claude.json ~/.claude.json.bak-$TS -[ -f .common/secrets/interns.env ] && cp .common/secrets/interns.env .common/secrets/interns.env.bak-$TS +[ -f ~/projects/.common/secrets/interns.env ] && cp ~/projects/.common/secrets/interns.env ~/projects/.common/secrets/interns.env.bak-$TS ``` Confirm both backups exist (when their source existed) before any further edit. -### Phase 4 — Install Python module +### Phase 4 — Clone (if needed) + Install Python module + +**Clone.** If Phase 1 found the source absent: ```bash -# from project root -python -m pip install -e .common/lib/interns-mcp/ +mkdir -p ~/projects/.common/lib +git clone https://git.kzntsv.site/OpeItcLoc03/interns-mcp ~/projects/.common/lib/interns-mcp +``` + +Verify `~/projects/.common/lib/interns-mcp/pyproject.toml` exists after clone. If not — abort. + +If the source was already present and Phase 1 found `interns_mcp` importable, skip both clone and install. + +**Install.** If Phase 1 found `interns_mcp` not importable: + +```bash +python -m pip install -e ~/projects/.common/lib/interns-mcp/ ``` Capture the resolved `python` from Phase 0; use the same interpreter for both `pip install` and the later MCP `command:` field. Verify post-install: @@ -123,12 +142,12 @@ If Phase 1 flagged a missing `.gitignore` rule, append it first: .common/secrets/*.env ``` -Then write `.common/secrets/interns.env`. Per-key behavior: +Then write `~/projects/.common/secrets/interns.env`. Per-key behavior: - Existing key in the file with a non-empty value — leave it alone. - Missing key — append `=` if the user pasted one, or `=` (blank) if the user skipped. A blank entry will fail at runtime with a clear `KeyError`; that's acceptable for the "I'll fill it later" path. -Permissions: on Linux / macOS run `chmod 600 .common/secrets/interns.env`. On Windows the default ACL is per-user, no extra step. +Permissions: on Linux / macOS run `chmod 600 ~/projects/.common/secrets/interns.env`. On Windows the default ACL is per-user, no extra step. ### Phase 6 — Register in `~/.claude.json` @@ -140,13 +159,13 @@ Edit `~/.claude.json`. Add or update the `mcpServers.interns` block: "interns": { "command": "", "args": ["-m", "interns_mcp.server"], - "cwd": "" + "cwd": "~/projects" } } } ``` -`cwd` is set so the runtime resolves `.common/config/interns/config.yaml` and `.common/secrets/interns.env` relative to project root regardless of where Claude Code was launched. +`cwd` is set so the runtime resolves `.common/config/interns/config.yaml` and `.common/secrets/interns.env` relative to the `~/projects` base directory regardless of where Claude Code was launched. On Windows, expand `~/projects` to the absolute path (e.g. `C:/Users//projects`). Absolute interpreter path comes from Phase 0 (`sys.executable`). Forward slashes work in JSON on Windows without escaping. @@ -176,13 +195,14 @@ If `mcp__interns__*` tools aren't registered in this session at all, skip the sm Tell the user: ``` -✅ Setup complete. Restart Claude Code so the new mcpServers.interns - registration binds to a fresh stdio session. +Setup complete. Restart Claude Code so the new mcpServers.interns +registration binds to a fresh stdio session. After restart: • mcp__interns__* tools serve from -m interns_mcp.server - • Endpoint keys live in .common/secrets/interns.env (gitignored) - • Config catalog at .common/config/interns/config.yaml + • Source at ~/projects/.common/lib/interns-mcp/ + • Endpoint keys live in ~/projects/.common/secrets/interns.env (gitignored) + • Config catalog at ~/projects/.common/config/interns/config.yaml • Backups saved at ~/.claude.json.bak- (and interns.env.bak- if it existed before) @@ -199,12 +219,13 @@ If something breaks after restart: If a problem surfaces (now or after restart): 1. Stop. Don't try to fix forward. -2. Find the most recent `.bak-YYYYMMDD-HHMMSS` next to `~/.claude.json` and `.common/secrets/interns.env`. +2. Find the most recent `.bak-YYYYMMDD-HHMMSS` next to `~/.claude.json` (and `~/projects/.common/secrets/interns.env` if applicable). 3. `cp .bak- ` for each. 4. Optional: `pip uninstall interns-mcp` if you want to remove the editable install. -5. Restart Claude Code. -6. Confirm `mcp__interns__*` is gone (or back to its pre-existing version). -7. Report what went wrong so we can fix the procedure. +5. Optional: `rm -rf ~/projects/.common/lib/interns-mcp` if you want to remove the cloned source. +6. Restart Claude Code. +7. Confirm `mcp__interns__*` is gone (or back to its pre-existing version). +8. Report what went wrong so we can fix the procedure. ## Cross-platform notes @@ -216,15 +237,16 @@ The procedure is platform-agnostic. Only auxiliary tooling differs: | Linux | `jq empty ` (or `python -c "import json; json.load(open(''))"`) | `cp` | `chmod 600` | | macOS | same as Linux | `cp` | `chmod 600` | -POSIX-style paths (`.common/...`, `~/.claude.json`) work on all three. +Path forms (`~/projects/.common/...`, `~/.config/...`, `~/.claude.json`) are identical on all three. ## Common mistakes - **Skipping Phase 1.** "User just said 'install interns' — let's go." No — find existing source / module / keys first; clobbering an existing `.env` over a working one loses keys you can't recover. - **Echoing endpoint keys.** They're secrets. Edit / Write tool calls inevitably contain them (that's how they land in `.env`), but no chat output should. - **Pinning `python` instead of ``.** A bare `python` in the MCP `command:` resolves to whatever interpreter is first on `PATH` at session start — often a different env without the `interns_mcp` module. Always use the absolute interpreter path captured in Phase 0. -- **Forgetting `cwd:`.** Without it the runtime can't find `.common/config/interns/config.yaml` and bombs at startup with a config-not-found error that looks like a Claude Code bug. +- **Forgetting `cwd: ~/projects`.** Without it the runtime can't find `.common/config/interns/config.yaml` and bombs at startup with a config-not-found error that looks like a Claude Code bug. - **Writing `.env` with `0644` perms on Linux/macOS.** Token leak. Always `chmod 600` after write. - **Missing the gitignore rule.** Tokens commit to the repo on the next `git add .`. Always check `.gitignore` covers `.common/secrets/*.env` before writing — Phase 5 does it but it's worth double-checking. - **Treating in-session smoke test as proof.** Same as the context7 / projects-meta caveat — the active MCP connection was bound at session start. Real verification happens after restart. - **Auto-running on every "use interns".** This skill is intrusive. Trigger only on explicit "install / set up / configure interns", or when MCP tools are missing and the user is blocked. +- **Cloning over an existing source directory.** If `~/projects/.common/lib/interns-mcp/` already exists with `pyproject.toml`, don't clone — use what's there. Clone is only for the "source not found" case. \ No newline at end of file