Defame1297
117e07fc43
- 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
128 lines
11 KiB
Markdown
128 lines
11 KiB
Markdown
---
|
|
name: neuledge-context
|
|
description: "Use when the user wants to install @neuledge/context, register it as a Claude Code MCP server, manage documentation packages (install, browse, add, remove, list), configure custom registries, or manage auth for private registries. Do NOT use when the user wants to install a different MCP server, wants to query docs from an already-running context server (call `get_docs` directly), or is setting up @neuledge/context for Cursor, VS Code Copilot, or Claude Desktop rather than Claude Code."
|
|
metadata:
|
|
category: cross-cutting
|
|
allowed-tools:
|
|
- Bash
|
|
- Read
|
|
- Edit
|
|
---
|
|
|
|
<requirements>
|
|
|
|
## Required inputs
|
|
|
|
- **Task type** — install / register-mcp / package-management / auth / upgrade / uninstall; inferred from user request, ask if ambiguous
|
|
- **Package name(s)** (package management only) — name(s) to install, add, or remove; ask if not stated
|
|
- **Library list** (project MCP scope only) — space-separated lib names for `--libs`; ask if not stated
|
|
- **Domain** (auth only) — domain to authenticate against; ask if not stated
|
|
- **Credential reference** (auth only) — environment variable or secret manager path holding the token or cookie; never the raw value
|
|
|
|
## Constraints
|
|
|
|
- Run `scripts/setup-neuledge-context.sh <VERSION>` for install and upgrade — never run `npm install -g @neuledge/context@latest`
|
|
- Run `scripts/secure-context-config.sh` immediately after every `context auth add` — never skip the permissions step
|
|
- Check `git --version` before running `context add` on a URL or GitHub source; skip the check for local `.db` file paths
|
|
- Never echo, repeat, or log auth token or cookie values — reference the environment variable name only
|
|
- Scope all steps to stdio mode; HTTP/Docker mode is documented in `references/http-mode.md`, not covered here
|
|
- State what you are about to do before running `setup-neuledge-context.sh` — it modifies global npm and Claude Code MCP config
|
|
|
|
</requirements>
|
|
|
|
<steps>
|
|
|
|
## Process
|
|
|
|
1. **Identify task.** Infer the task type from the user's request. If the request spans multiple tasks (e.g. install + package install), execute them in the order listed below.
|
|
|
|
2. **Install.** (Skip if `context --version` already returns the target version.)
|
|
- State: "I will run `scripts/setup-neuledge-context.sh` from the ai-development repo root — this installs `@neuledge/context` globally at the pinned version."
|
|
- Run: `bash scripts/setup-neuledge-context.sh` from `/root/ai-development/`
|
|
- 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 at user scope.)
|
|
- Check: `claude mcp list | grep '^context '` — if output is non-empty, skip.
|
|
- 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.
|
|
- 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.
|
|
|
|
5. **Manage packages.**
|
|
- **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 (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` — 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.
|
|
- Immediately run: `bash scripts/secure-context-config.sh` from `/root/ai-development/`
|
|
|
|
7. **Configure custom registry.** (Self-hosted registry server.)
|
|
- Read `~/.context/config.json`. Add a server entry following the schema in `references/context-cli-reference.md`.
|
|
- Test: `context browse <package> --server <name>`
|
|
|
|
8. **Upgrade.** Run `bash scripts/setup-neuledge-context.sh <TARGET_VERSION>` from `/root/ai-development/`. The script checks the current version and skips if already at target.
|
|
|
|
9. **Uninstall.**
|
|
- Run: `npm uninstall -g @neuledge/context`
|
|
- Ask the user before removing downloaded packages: `rm -rf ~/.context` deletes all installed documentation and config — confirm before running.
|
|
|
|
## Output format
|
|
|
|
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 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)
|
|
|
|
</steps>
|
|
|
|
<checks>
|
|
|
|
## Failure handling
|
|
|
|
- `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 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.
|
|
- `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
|
|
|
|
- [ ] 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 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` — 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`
|
|
- [ ] No credential values echoed or logged — environment variable references only
|
|
- [ ] `context remove <name>@<version>` used (not bare name) when targeting a specific version
|
|
- [ ] `rm -rf ~/.context` confirmed with user before running
|
|
|
|
</checks>
|