fix(skills): update neuledge-context with session lessons
- Fix claude mcp add scope flag: -s user for global, -s project for per-project --libs (--project flag does not exist) - Project scope writes to .mcp.json (committed); not settings.local.json - Document dual-scope pattern and expected conflict warning - Document MCP tools not available mid-session after claude mcp add; require /reload-plugins or new session - Expand context add step with llms.txt-first workflow for registry gaps (Anthropic, Claude Code, MCP docs not in public registry) - Fix self-check: explicit scope flag required, context list for identifiers - Add .mcp.json with project-scoped context serve --libs for this repo Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TP4EGbBg3XMcyF28Lx78XJ
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
```yaml
|
||||
version: "1.0"
|
||||
updated: 2026-06-20
|
||||
version: "1.1"
|
||||
updated: 2026-06-21
|
||||
|
||||
when: Invoked when the user asks to install @neuledge/context, wire it as a Claude Code MCP server, manage documentation packages from the registry or custom sources, configure custom registry servers, or manage private registry auth. Also invoked when the user wants to scope an MCP session to specific libraries via --libs.
|
||||
|
||||
|
||||
@@ -42,22 +42,32 @@ allowed-tools:
|
||||
- Verify: `context --version`
|
||||
- See `references/install-notes.md` for prerequisites and native SQLite build tool requirements.
|
||||
|
||||
3. **Register global MCP server.** (One-time per machine. Skip if already registered.)
|
||||
3. **Register global MCP server.** (One-time per machine. Skip if already registered at user scope.)
|
||||
- Check: `claude mcp list | grep '^context '` — if output is non-empty, skip.
|
||||
- Run: `claude mcp add context -- context serve`
|
||||
- Run: `claude mcp add -s user context -- context serve`
|
||||
- Confirm: `claude mcp list`
|
||||
- Note: the default scope for `claude mcp add` is `local` (machine-specific, not shared). Always pass `-s user` for global availability across all projects.
|
||||
- Note: MCP tools (`search_packages`, `get_docs`, `download_package`) only appear in the active session after `/reload-plugins` or starting a new session — they are not immediately available mid-session after registration.
|
||||
|
||||
4. **Scope MCP to specific libraries (optional, per-project).** (When user wants to restrict the MCP session to pre-approved libraries for a project.)
|
||||
- Collect the library list from the user if not stated.
|
||||
- For each named library, run `context browse <name>` to confirm the exact package identifier (e.g. `react` vs `npm/react`, `next` vs `nextjs`). Use the identifier shown in the browse output — do not guess. If `context list` shows the package is already installed, that identifier is authoritative.
|
||||
- Run: `claude mcp add --project context -- context serve --libs <verified-id1> <verified-id2> ...`
|
||||
- Note: this overrides the global registration for the current project only. The `search_packages` and `download_package` MCP tools are hidden; only `get_docs` is available for the listed libraries.
|
||||
- Verify each identifier: run `context list` for already-installed packages (authoritative) or `context browse <name>` for registry packages. Do not guess identifiers.
|
||||
- Run: `claude mcp add -s project context -- context serve --libs <verified-id1> <verified-id2> ...`
|
||||
- This writes to `.mcp.json` in the project root — commit this file to share the scope with the team.
|
||||
- If both user and project scopes exist for the same server name, Claude Code will warn about dual registration — this is expected. Project scope overrides user scope within the project directory.
|
||||
- Note: with `--libs`, the `search_packages` and `download_package` MCP tools are hidden; only `get_docs` is available for the listed libraries.
|
||||
|
||||
5. **Manage packages.**
|
||||
- **Browse registry:** `context browse <name>` — shows available versions.
|
||||
- **Browse registry:** `context browse <name>` — shows available versions. The public registry is JS/frontend-focused; key AI/agent packages (Anthropic SDK, Claude Code, MCP SDK) are absent — use `context add` for those.
|
||||
- **Install from registry:** `context install <registry/name> [version]` — e.g. `context install npm/react`.
|
||||
- **Add from source:** Check `git --version` first if source is a URL or GitHub repo. Run: `context add <source> [--path <docs-path>] [--tag <tag>] [--name <name>]`. See `references/context-cli-reference.md` for all flags.
|
||||
- **List installed:** `context list`
|
||||
- **Add from source (for registry gaps):** Many docs sites publish `llms.txt`; prefer that over cloning. Check `<url>/llms.txt` or `<url>/llms-full.txt` before falling back to GitHub. Check `git --version` first if source is a GitHub repo URL.
|
||||
```bash
|
||||
context add https://docs.anthropic.com --name claude-docs # llms.txt site
|
||||
context add https://modelcontextprotocol.io --name mcp-docs # llms.txt site
|
||||
context add https://github.com/org/repo --path docs --name mylib # GitHub repo
|
||||
```
|
||||
See `references/context-cli-reference.md` for all flags.
|
||||
- **List installed:** `context list` — use this to get the exact installed identifier for `--libs`.
|
||||
- **Remove:** `context remove <name>@<version>` to target a specific version; `context remove <name>` removes all versions — confirm with the user before removing all.
|
||||
|
||||
6. **Configure auth.** (Private registries or subscriber-only content.)
|
||||
@@ -78,7 +88,7 @@ allowed-tools:
|
||||
|
||||
No structured output file. The skill produces terminal confirmation of each completed step. Artifacts:
|
||||
- `@neuledge/context` installed globally at pinned version
|
||||
- MCP server entry in `~/.claude/settings.json` (global) or `.claude/settings.local.json` (project)
|
||||
- MCP server entry in user config (global, `-s user`) or `.mcp.json` in project root (project-scoped, `-s project`, committed to repo)
|
||||
- Downloaded `.db` packages in `~/.context/packages/`
|
||||
- Modified `~/.context/config.json` (auth entries, registry config)
|
||||
|
||||
@@ -90,7 +100,9 @@ No structured output file. The skill produces terminal confirmation of each comp
|
||||
|
||||
- `scripts/setup-neuledge-context.sh` not found — stop; instruct user to run from `/root/ai-development/`
|
||||
- `context` binary not found after install — report npm error; check `node --version` is ≥18
|
||||
- MCP registration fails — run `claude mcp list` to check for name conflicts; if `context` is already registered with different args, report it and ask the user to remove it first with `claude mcp remove context`
|
||||
- MCP registration fails — run `claude mcp list` to check for name conflicts; if `context` is registered with different args or at the wrong scope, remove with `claude mcp remove context -s <scope>` and re-add at the correct scope
|
||||
- MCP tools not visible after registration — `claude mcp add` mid-session does not immediately expose tools; run `/reload-plugins` or start a new session
|
||||
- Dual-scope warning after adding project scope — expected when user and project scopes both define `context`; project takes precedence in the project directory. Remove the unwanted scope with `claude mcp remove context -s <scope>`
|
||||
- `context add` fails with "git not found" — advise `apt-get install git` (Debian/Ubuntu) or equivalent; re-run after install
|
||||
- Native SQLite build failure — Context falls back to WASM automatically; advise installing build tools for better performance: `apt-get install -y python3 make g++` on Debian/Ubuntu. See `references/install-notes.md` for known gotchas.
|
||||
|
||||
@@ -98,7 +110,10 @@ No structured output file. The skill produces terminal confirmation of each comp
|
||||
|
||||
- [ ] Task type identified before any commands run
|
||||
- [ ] `setup-neuledge-context.sh` announced before execution
|
||||
- [ ] `claude mcp list` checked before `claude mcp add` — skipped if already registered
|
||||
- [ ] `claude mcp list` checked before `claude mcp add` — skipped if already registered at correct scope
|
||||
- [ ] `-s user` used for global registration; `-s project` used for `--libs` project scope — never relied on default (`local`) scope
|
||||
- [ ] `context list` used to get authoritative identifiers before composing `--libs`
|
||||
- [ ] `.mcp.json` noted for commit when project scope is added
|
||||
- [ ] `git --version` checked before `context add` on a URL or GitHub source
|
||||
- [ ] Auth step: `secure-context-config.sh` run immediately after every `context auth add`
|
||||
- [ ] No credential values echoed or logged — environment variable references only
|
||||
|
||||
Reference in New Issue
Block a user