fix(skills): fix --libs identifier format and rebuild claude-code-docs

- neuledge-context v1.2: document that --libs identifiers must include
  version suffix verbatim from `context list` (e.g. name@latest);
  add rebuild workflow for packages with bad crawl/low section count;
  add failure cases for get_docs returning Package not found and
  /reload-plugins not restarting stdio MCP processes
- .mcp.json: fix all --libs identifiers to include @latest suffix;
  update claude-code-docs to @2.1.98 (rebuilt from GitHub, 636 sections
  vs 9 from the previous bad web crawl)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TP4EGbBg3XMcyF28Lx78XJ
This commit is contained in:
2026-06-21 00:22:43 +00:00
parent 0c73c21c9a
commit 117e07fc43
3 changed files with 14 additions and 10 deletions

View File

@@ -51,9 +51,10 @@ allowed-tools:
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.
- Verify each identifier: run `context list` for already-installed packages (authoritative) or `context browse <name>` for registry packages. Do not guess identifiers.
- Verify each identifier: run `context list` — copy the identifier **exactly** as shown, including any version suffix (e.g., `claude-code-docs@latest`, not `claude-code-docs`). The `--libs` filter does an exact string match; a bare name without the suffix will silently exclude the package and `get_docs` will return "Package not found". For registry packages not yet installed, use `context browse <name>` to find the name, then install and re-run `context list`.
- 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.
- `.mcp.json` can also be edited directly if the identifier list needs updating. Changes take effect only in a new Claude Code session — `/reload-plugins` reloads skill manifests but does not restart stdio MCP server processes.
- 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.
@@ -67,8 +68,9 @@ allowed-tools:
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`.
- **List installed:** `context list` — shows name, version, size, and section count. Section count is a health signal: a package with 0 or very few sections relative to its KB size was probably not indexed correctly.
- **Remove:** `context remove <name>@<version>` to target a specific version; `context remove <name>` removes all versions — confirm with the user before removing all.
- **Rebuild (when a package returns no query results):** A package can install successfully but produce no FTS5 search results if the source URL returned sparse content (e.g., a redirect page instead of the actual docs). Diagnose by checking section count in `context list` — a large KB size with few sections is a sign of a bad crawl. Fix: `context remove <name>` (confirm first), then re-add from a better source. Try `<url>/llms-full.txt` before `<url>/llms.txt` before the GitHub repo — `llms-full.txt` produces the most sections. After rebuild, verify with `context list` that section count has increased and spot-check with `context query <name> <topic>`.
6. **Configure auth.** (Private registries or subscriber-only content.)
- Run: `context auth add <domain> --header "Authorization: Bearer $TOKEN"` — use the environment variable name, not the value.
@@ -105,6 +107,8 @@ No structured output file. The skill produces terminal confirmation of each comp
- 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.
- `get_docs` returns "Package not found" for a package that appears in `context list` — two causes: (1) `--libs` identifier mismatch: the identifier in `.mcp.json` must exactly match `context list` output including version suffix; edit `.mcp.json` and start a new session to apply; (2) bad crawl: the package indexed 0 or very few sections — rebuild per the Rebuild workflow in step 5.
- `get_docs` returns results via CLI (`context query`) but not via MCP — the MCP server process is using the old `--libs` config from when the session started; changes to `.mcp.json` require a new session, `/reload-plugins` is not sufficient.
## Self-check
@@ -112,7 +116,7 @@ No structured output file. The skill produces terminal confirmation of each comp
- [ ] `setup-neuledge-context.sh` announced before execution
- [ ] `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`
- [ ] `context list` used to get authoritative identifiers before composing `--libs` — identifiers copied verbatim including version suffix (e.g., `name@latest`)
- [ ] `.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`