diff --git a/docs/clients/cli.mdx b/docs/clients/cli.mdx index 460f11ee2..bd208cf55 100644 --- a/docs/clients/cli.mdx +++ b/docs/clients/cli.mdx @@ -190,6 +190,21 @@ When `--base-url` targets a custom deployment, setup skips the npm update check | ---------------------- | ------------------------------------------------------------------------------ | | Agent skills directory | `docs` skill — guides the agent to use `ctx7 library` and `ctx7 docs` commands | +### Skill installation + +`ctx7 setup` installs a skill alongside the rule and MCP config: + +- **MCP mode** downloads the `context7-mcp` skill from GitHub. If the download fails, setup falls back to a bundled copy of the skill (`installed (bundled fallback)`) and still completes — the skill install is not a hard failure. +- **CLI + Skills mode** downloads the `find-docs` skill. If that download fails, setup stops with an error before installing anything. + +Skills are written to the agent's skills directory — for example `.agents/skills/` for Codex and other universal agents, `.claude/skills/` for Claude Code, `.cursor/skills/` for Cursor. To retry or install manually after a failure, use the skills command: + +```bash +ctx7 skills install /upstash/context7 context7-mcp +``` + +or place the `SKILL.md` manually in the target skills directory. The source file lives at [`skills/context7-mcp/SKILL.md`](https://github.com/upstash/context7/blob/master/skills/context7-mcp/SKILL.md) in the repository. + ### ctx7 remove Remove the setup written by `ctx7 setup`. By default this removes both MCP setup and CLI setup for the selected agent. diff --git a/docs/clients/codex.mdx b/docs/clients/codex.mdx index a71050ec5..34bb31447 100644 --- a/docs/clients/codex.mdx +++ b/docs/clients/codex.mdx @@ -123,6 +123,10 @@ How does Supabase storage work? ``` + +If you use CLI + Skills mode, `ctx7 setup` installs guidance telling Codex to run Context7 CLI requests outside its default sandbox. If a `ctx7` command fails with DNS or network errors (such as `ENOTFOUND`, host resolution failures, or `fetch failed`), rerun it outside the sandbox instead of retrying inside it. + + If you see a startup "request timed out" or "not found program" error, increase `startup_timeout_ms` to `40_000` and retry. On Windows, point `command` at the absolute `npx.cmd` path and set `SystemRoot` and `APPDATA` explicitly — `npx` requires them, but some Codex MCP clients don't set them by default. diff --git a/docs/docs.json b/docs/docs.json index 57c4357ec..ae0932df4 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -238,7 +238,7 @@ { "group": "Resources", "expanded": false, - "pages": ["resources/developer", "resources/troubleshooting"] + "pages": ["resources/developer", "resources/technical-reference", "resources/troubleshooting"] } ] } diff --git a/docs/resources/developer.mdx b/docs/resources/developer.mdx index 030c784a2..c90b1a7b5 100644 --- a/docs/resources/developer.mdx +++ b/docs/resources/developer.mdx @@ -90,6 +90,30 @@ CONTEXT7_API_KEY=your_api_key_here } ``` +## MCP Tools + +The server registers two tools. Both are read-only, idempotent, and open-world (annotations: `readOnlyHint`, `idempotentHint`, and `openWorldHint` are `true`; `destructiveHint` is `false`). + +### resolve-library-id + +Resolves a package/product name to a Context7-compatible library ID and returns matching libraries. Call this before `query-docs` unless the user already provides a library ID in `/org/project` or `/org/project/version` format. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `libraryName` | string | yes | Library name to search for and resolve to a Context7-compatible library ID. Use the official name with proper punctuation (e.g., "Next.js" not "nextjs"). | +| `query` | string | yes | What to look up in the library's documentation, used to rank results by relevance. Sent to the Context7 API; do not include sensitive or confidential information. | + +### query-docs + +Retrieves and queries up-to-date documentation and code examples for a library. Requires a valid library ID from `resolve-library-id` (or one provided directly by the user). + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `libraryId` | string | yes | Exact Context7-compatible library ID (e.g., `/vercel/next.js` or `/vercel/next.js/v14.3.0-canary.87`). | +| `query` | string | yes | What to look up, scoped to a single concept. Make a separate call per concept unless the question is about how concepts interact. Do not include sensitive or confidential information. | + +The server declares the `prompts` and `resources` capabilities but registers no prompts and no resources — `prompts/list` and `resources/list` answer with empty collections. + ## Local Development Configuration When developing locally, use this configuration to run from source: diff --git a/docs/resources/technical-reference.mdx b/docs/resources/technical-reference.mdx new file mode 100644 index 000000000..cc80211b6 --- /dev/null +++ b/docs/resources/technical-reference.mdx @@ -0,0 +1,39 @@ +--- +title: Technical Reference +description: Package names, versions, runtime requirements, and version migration notes for the Context7 SDK, CLI, and MCP server +--- + +Reference for the Context7 packages: current versions, runtime requirements, and breaking changes to watch for when upgrading. + +## Packages + +| Package | npm name | Current version | Node.js | +|---------|----------|-----------------|---------| +| CLI | [`ctx7`](https://www.npmjs.com/package/ctx7) | `0.5.11` | 18+ | +| MCP server | [`@upstash/context7-mcp`](https://www.npmjs.com/package/@upstash/context7-mcp) | `4.0.7` | 20.18.1+ | +| TypeScript SDK | [`@upstash/context7-sdk`](https://www.npmjs.com/package/@upstash/context7-sdk) | `0.4.1` | 18+ | + +Related packages: [`@upstash/context7-tools-ai-sdk`](https://www.npmjs.com/package/@upstash/context7-tools-ai-sdk) (Vercel AI SDK tools) and [`@upstash/context7-pi`](https://www.npmjs.com/package/@upstash/context7-pi) (pi.dev extension). + +For how queries are stored and used (reranking providers, retention, and enterprise opt-out), see [Data Privacy](/security/data-privacy). + +## Versioning & Migration + +Breaking changes and deprecations to be aware of when upgrading. + +### SDK — v0.2.0 API simplification + +The SDK API was simplified in `0.2.0`: + +- `getDocs()` was replaced by `getContext(query, libraryId, options)`, which takes a `query` for relevance-based retrieval +- `searchLibrary(query, libraryName)` now takes both a query and a library name +- Response types were renamed (`Library` and `Documentation` instead of `SearchResult`, `CodeDocsResponse`, etc.) +- Pagination, mode, topic, and limit options were removed from context retrieval + +### CLI — research mode removed (v0.4.1) + +Research mode was removed entirely. The `query-docs` MCP tool no longer accepts or forwards a `researchMode` parameter, and the CLI no longer exposes a `--research` flag on `ctx7 docs`. + +### CLI — skill commands deprecated + +The `ctx7 skills ...` commands are deprecated and will stop working in the next major release. The `context7-mcp` and `find-docs` skills installed by `ctx7 setup` are unaffected. \ No newline at end of file diff --git a/docs/tips.mdx b/docs/tips.mdx index ad881cf7f..8469d1863 100644 --- a/docs/tips.mdx +++ b/docs/tips.mdx @@ -36,3 +36,12 @@ How do I set up Next.js 14 middleware? use context7 ``` Context7 will automatically match the appropriate version. + +## Query Strategy + +Context7 grounds your assistant with up-to-date docs, but the quality of what it retrieves depends on how the retrieval is scoped. These habits keep the retrieved context minimal and relevant: + +- **Retrieve only when needed** — Context7 is for library, framework, SDK, API, and CLI-tool questions. Skip it for refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts. +- **One concept per query** — scope each query to a single topic. Split multi-topic questions (e.g. "routing and auth and caching") into a separate query per concept, unless the question is about how the concepts interact. Combined queries dilute ranking and return shallow results for each topic. +- **Be specific, not vague** — a query like `"How to set up authentication with JWT in Express.js"` returns far better results than `"auth"` or `"hooks"`. +- **Keep the context relevant** — don't include sensitive or confidential information in queries, and use the best-matching library ID (and version-specific ID when a version matters) so you don't pull docs for the wrong package.