commit 54d55568705922facdc535406c46bf6076aec81a Author: wehub-resource-sync Date: Mon Jul 13 13:04:05 2026 +0800 chore: import upstream snapshot with attribution diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..a017b9b --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "context7-marketplace", + "interface": { + "displayName": "Context7 Marketplace" + }, + "plugins": [ + { + "name": "context7", + "source": { + "source": "local", + "path": "./plugins/codex/context7" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_USE" + }, + "category": "Developer Tools" + } + ] +} diff --git a/.changeset/README.md b/.changeset/README.md new file mode 100644 index 0000000..e5b6d8d --- /dev/null +++ b/.changeset/README.md @@ -0,0 +1,8 @@ +# Changesets + +Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works +with multi-package repos, or single-package repos to help you version and publish your code. You can +find the full documentation for it [in our repository](https://github.com/changesets/changesets) + +We have a quick list of common questions to get you started engaging with this project in +[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md) diff --git a/.changeset/bump-jose-6-2-3.md b/.changeset/bump-jose-6-2-3.md new file mode 100644 index 0000000..4abefa7 --- /dev/null +++ b/.changeset/bump-jose-6-2-3.md @@ -0,0 +1,5 @@ +--- +"@upstash/context7-mcp": patch +--- + +Bump jose from 6.1.3 to 6.2.3. diff --git a/.changeset/config.json b/.changeset/config.json new file mode 100644 index 0000000..938f047 --- /dev/null +++ b/.changeset/config.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json", + "changelog": "@changesets/cli/changelog", + "commit": false, + "fixed": [], + "linked": [], + "access": "public", + "baseBranch": "master", + "updateInternalDependencies": "patch", + "ignore": [], + "snapshot": { + "useCalculatedVersion": true, + "prereleaseTemplate": "{tag}-{datetime}" + } +} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..9a32fe7 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,14 @@ +{ + "name": "context7-marketplace", + "owner": { + "name": "Upstash" + }, + "plugins": [ + { + "name": "context7", + "source": "./plugins/claude/context7", + "description": "Up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.", + "version": "1.0.2" + } + ] +} diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..3c7ccc0 --- /dev/null +++ b/.env.example @@ -0,0 +1,24 @@ +# Context7 API +CONTEXT7_API_KEY= +CONTEXT7_API_URL=https://context7.com/api + +# MCP HTTP server +UPSTASH_REDIS_REST_URL= +UPSTASH_REDIS_REST_TOKEN= +RESOURCE_URL= +AUTH_SERVER_URL= +OPENAI_APPS_CHALLENGE_TOKEN= +CLIENT_IP_ENCRYPTION_KEY= + +# Network / certificates +HTTPS_PROXY= +NODE_EXTRA_CA_CERTS= + +# GitHub integration +GITHUB_TOKEN= +GH_TOKEN= + +# CLI behavior +CLAUDE_CONFIG_DIR= +CTX7_TELEMETRY_DISABLED= +EDITOR= diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..c265cc3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,127 @@ +name: Bug Report +description: Report a bug or issue with Context7 MCP +title: "[Bug]: " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report this issue! Please fill out the form below to help us investigate. + + - type: dropdown + id: client + attributes: + label: MCP Client + description: Which MCP client are you using? + options: + - Cursor + - Claude Desktop + - Claude Code + - Devin Desktop + - VS Code + - Cline + - Zed + - Other (specify in description) + validations: + required: true + + - type: input + id: version + attributes: + label: Context7 MCP Version + description: Which version of Context7 MCP are you using? (Check package.json or npm list) + placeholder: e.g., 1.0.21 + validations: + required: true + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear description of what the bug is + placeholder: When I try to... + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior + placeholder: | + 1. Install Context7 MCP via... + 2. Run the command... + 3. See error... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What you expected to happen + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Error Messages / Logs + description: Please copy and paste any relevant error messages or logs + render: shell + + - type: dropdown + id: transport + attributes: + label: Transport Method + description: Which transport method are you using? + options: + - stdio (default) + - http + - SSE (deprecated) + validations: + required: true + + - type: input + id: node-version + attributes: + label: Node.js Version + description: Output of `node --version` + placeholder: e.g., v20.10.0 + + - type: input + id: os + attributes: + label: Operating System + description: Which OS are you running? + placeholder: e.g., macOS 14.2, Windows 11, Ubuntu 22.04 + + - type: textarea + id: config + attributes: + label: Configuration + description: Your Context7 MCP configuration (remove any API keys!) + render: json + placeholder: | + { + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } + } + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Any other context about the problem (proxy settings, firewalls, etc.) diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 0000000..447af35 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,50 @@ +name: Documentation Issue +description: Report incorrect or missing documentation +title: "[Docs]: " +labels: ["documentation"] +body: + - type: markdown + attributes: + value: | + Found an issue with Context7 documentation? Let us know! + + - type: dropdown + id: doc-type + attributes: + label: Documentation Type + description: Where is the issue? + options: + - README + - Installation instructions + - API documentation + - Library-specific docs + - Configuration examples + validations: + required: true + + - type: textarea + id: issue + attributes: + label: Issue Description + description: What's wrong or missing? + validations: + required: true + + - type: input + id: location + attributes: + label: Documentation Location + description: Link or section name where the issue exists + placeholder: e.g., README.md line 45, or "Installation via Smithery" section + + - type: textarea + id: suggestion + attributes: + label: Suggested Fix + description: How should it be corrected or what should be added? + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Any other relevant information diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..6f7055a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,51 @@ +name: Feature Request +description: Suggest a new feature or improvement +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a feature! We appreciate your input. + + - type: textarea + id: problem + attributes: + label: Problem Description + description: Is your feature request related to a problem? Please describe. + placeholder: I'm frustrated when... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like + placeholder: I would like Context7 to... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Describe any alternative solutions or features you've considered + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Nice to have + - Would improve my workflow + - Blocking my usage + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Add any other context, screenshots, or examples about the feature request diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..d3a1ced --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,18 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: / + schedule: + interval: monthly + - package-ecosystem: bun + directory: / + schedule: + interval: monthly + - package-ecosystem: docker + directory: / + schedule: + interval: monthly + - package-ecosystem: github-actions + directory: / + schedule: + interval: monthly diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json new file mode 100644 index 0000000..7342e15 --- /dev/null +++ b/.github/plugin/marketplace.json @@ -0,0 +1,18 @@ +{ + "name": "context7-marketplace", + "owner": { + "name": "Upstash" + }, + "metadata": { + "description": "Official Upstash marketplace for the Context7 documentation-lookup plugin on GitHub Copilot CLI.", + "version": "1.0.0" + }, + "plugins": [ + { + "name": "context7", + "source": "./plugins/copilot/context7", + "description": "Up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.", + "version": "1.0.2" + } + ] +} diff --git a/.github/workflows/canary-release.yml b/.github/workflows/canary-release.yml new file mode 100644 index 0000000..b11fe8d --- /dev/null +++ b/.github/workflows/canary-release.yml @@ -0,0 +1,46 @@ +name: Canary Release + +on: + workflow_dispatch: + inputs: + branch: + description: "Branch to release from (defaults to current branch)" + required: false + type: string + +jobs: + canary-release: + name: Canary Release + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Checkout Repo + uses: actions/checkout@v7 + with: + ref: ${{ inputs.branch || github.ref }} + + - name: Setup Node + uses: actions/setup-node@v6 + with: + node-version: "20" + + - name: Setup pnpm + uses: pnpm/action-setup@v4 + with: + version: 10 + + - name: Configure npm authentication + run: | + echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc + + - name: Install Dependencies + run: pnpm install --frozen-lockfile + + - name: Build all packages + run: pnpm build + + - name: Publish Snapshot + run: pnpm release:snapshot + env: + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/.github/workflows/ecr-deploy.yml b/.github/workflows/ecr-deploy.yml new file mode 100644 index 0000000..6e84938 --- /dev/null +++ b/.github/workflows/ecr-deploy.yml @@ -0,0 +1,57 @@ +name: Deploy to AWS ECR + +on: + workflow_dispatch: + inputs: + version: + description: "Docker image version tag (e.g., v0.0.22)" + required: true + type: string + +jobs: + build-and-push: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v7 + + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v6 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: ${{ secrets.AWS_REGION }} + + - name: Login to Amazon ECR + id: login-ecr + uses: aws-actions/amazon-ecr-login@v2 + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Build and push Docker image + id: build-push + uses: docker/build-push-action@v6 + with: + context: . + file: packages/mcp/Dockerfile + platforms: linux/amd64,linux/arm64 + push: true + tags: | + ${{ secrets.ECR_REGISTRY }}/${{ secrets.ECR_REPOSITORY }}:${{ inputs.version }} + cache-from: type=gha + cache-to: type=gha,mode=max + + - name: Create GitHub Summary + run: | + echo "## Docker Image Deployed Successfully" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "**Image Tag:** \`${{ inputs.version }}\`" >> $GITHUB_STEP_SUMMARY + echo "**Platforms:** \`linux/amd64\`, \`linux/arm64\`" >> $GITHUB_STEP_SUMMARY + echo "**Digest:** \`${{ steps.build-push.outputs.digest }}\`" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "**Status:** ✅ Image pushed to AWS ECR" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/mcp-registry.yml b/.github/workflows/mcp-registry.yml new file mode 100644 index 0000000..b5adecf --- /dev/null +++ b/.github/workflows/mcp-registry.yml @@ -0,0 +1,54 @@ +name: Publish to MCP Registry + +on: + workflow_dispatch: + inputs: + version: + description: "Version to publish (defaults to package.json version)" + required: false + type: string + +jobs: + publish-mcp: + name: Publish to MCP Registry + runs-on: ubuntu-latest + permissions: + id-token: write # Required for OIDC authentication with MCP Registry + contents: read + steps: + - name: Checkout Repo + uses: actions/checkout@v7 + + - name: Setup Node + uses: actions/setup-node@v6 + with: + node-version: lts/* + + - name: Set version + run: | + if [ -n "${{ inputs.version }}" ]; then + VERSION="${{ inputs.version }}" + # Remove 'v' prefix if it exists + VERSION="${VERSION#v}" + else + VERSION=$(node -p "require('./packages/mcp/package.json').version") + fi + echo "VERSION=$VERSION" >> $GITHUB_ENV + echo "Publishing version: $VERSION" + + - name: Update package version in server.json + run: | + echo $(jq --arg v "${{ env.VERSION }}" '.version = $v | .packages[0].version = $v' server.json) > server.json + + - name: Validate server.json + run: npx mcp-registry-validator validate server.json + + - name: Install MCP Publisher + run: | + curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.4.0/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher + + - name: Login to MCP Registry + run: ./mcp-publisher login github-oidc + + - name: Publish to MCP Registry + run: ./mcp-publisher publish diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..dd7e22e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,50 @@ +name: Release + +on: + push: + branches: + - master + +concurrency: ${{ github.workflow }}-${{ github.ref }} + +jobs: + release: + name: Release + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - name: Checkout Repo + uses: actions/checkout@v7 + + - name: Setup Node + uses: actions/setup-node@v6 + with: + node-version: "20" + + - name: Setup pnpm + uses: pnpm/action-setup@v4 + with: + version: 10 + + - name: Configure npm authentication + run: | + echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc + + - name: Install Dependencies + run: pnpm install --frozen-lockfile + + - name: Build all packages + run: pnpm build + + - name: Create Release PR or Publish + id: changesets + uses: changesets/action@v1 + with: + publish: pnpm release + commit: "chore(release): version packages" + title: "chore(release): version packages" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..3100bea --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,72 @@ +name: Test + +on: + pull_request: + paths: + - "packages/**" + - "package.json" + - "pnpm-lock.yaml" + - "pnpm-workspace.yaml" + - "tsconfig.json" + - "eslint.config.js" + - "prettier.config.mjs" + - ".github/workflows/test.yml" + push: + branches: [master] + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - name: Setup Node + uses: actions/setup-node@v6 + with: + node-version: "20" + + - name: Setup pnpm + uses: pnpm/action-setup@v4 + with: + version: 10 + + - name: Get pnpm store directory + id: pnpm-cache + shell: bash + run: | + echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT + + - name: Cache pnpm dependencies + uses: actions/cache@v6 + with: + path: ${{ steps.pnpm-cache.outputs.STORE_PATH }} + key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }} + restore-keys: | + ${{ runner.os }}-pnpm-store- + + - name: Install Dependencies + run: pnpm install --frozen-lockfile + + - name: Lint + run: pnpm lint:check + + - name: Format + run: pnpm format:check + + - name: Build + run: pnpm build + + - name: Typecheck + run: pnpm typecheck + + - name: Test + run: pnpm test + env: + AWS_REGION: ${{ secrets.AWS_REGION }} + AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }} + CONTEXT7_API_KEY: ${{ secrets.CONTEXT7_API_KEY }} diff --git a/.github/workflows/triage-library-report.yml b/.github/workflows/triage-library-report.yml new file mode 100644 index 0000000..f19a44a --- /dev/null +++ b/.github/workflows/triage-library-report.yml @@ -0,0 +1,40 @@ +name: Triage library report + +# When a "Library Report" issue is opened, forward it to the triage service so the agent can +# analyze it and post its findings as a comment. +# +# Cross-repo note: this issue lives here (upstash/context7) but the triage agent + its secrets +# (Redis/Vector/model creds + a token that can comment on this repo) live in the context7app +# deployment. A GitHub Action here cannot run the agent, so it only forwards the issue number to +# the app's endpoint with a shared secret; the app runs the read-only agent and posts the comment. +# +# Required repo secrets (Settings → Secrets and variables → Actions): +# TRIAGE_WEBHOOK_URL https:///api/triage/analyze +# TRIAGE_WEBHOOK_SECRET same value as TRIAGE_WEBHOOK_SECRET in the context7app environment + +on: + issues: + types: [opened] + +permissions: {} # no GITHUB_TOKEN needed — the app comments with its own token + +jobs: + triage: + if: contains(github.event.issue.title, 'Library Report') + runs-on: ubuntu-latest + steps: + - name: Forward to triage service + env: + TRIAGE_WEBHOOK_URL: ${{ secrets.TRIAGE_WEBHOOK_URL }} + TRIAGE_WEBHOOK_SECRET: ${{ secrets.TRIAGE_WEBHOOK_SECRET }} + ISSUE_NUMBER: ${{ github.event.issue.number }} + run: | + if [ -z "$TRIAGE_WEBHOOK_URL" ]; then + echo "TRIAGE_WEBHOOK_URL not configured; skipping triage." + exit 0 + fi + echo "Triaging issue #$ISSUE_NUMBER" + curl -fsS --max-time 180 -X POST "$TRIAGE_WEBHOOK_URL" \ + -H "Authorization: Bearer $TRIAGE_WEBHOOK_SECRET" \ + -H "Content-Type: application/json" \ + -d "{\"issueNumber\": $ISSUE_NUMBER}" diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cec4734 --- /dev/null +++ b/.gitignore @@ -0,0 +1,187 @@ +# Based on https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore + +# Logs + +logs +_.log +npm-debug.log_ +yarn-debug.log* +yarn-error.log* +lerna-debug.log* +.pnpm-debug.log* + +# Caches + +.cache + +# Diagnostic reports (https://nodejs.org/api/report.html) + +report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json + +# Runtime data + +pids +_.pid +_.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover + +lib-cov + +# Coverage directory used by tools like istanbul + +coverage +*.lcov + +# nyc test coverage + +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) + +.grunt + +# Bower dependency directory (https://bower.io/) + +bower_components + +# node-waf configuration + +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) + +build/Release + +# Dependency directories + +node_modules/ +jspm_packages/ + +# Snowpack dependency directory (https://snowpack.dev/) + +web_modules/ + +# TypeScript cache + +*.tsbuildinfo + +# Optional npm cache directory + +.npm + +# Optional eslint cache + +.eslintcache + +# Optional stylelint cache + +.stylelintcache + +# Microbundle cache + +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history + +.node_repl_history + +# Output of 'npm pack' + +*.tgz + +# Yarn Integrity file + +.yarn-integrity + +# dotenv environment variable files + +.env +.env.development.local +.env.test.local +.env.production.local +.env.local + +# parcel-bundler cache (https://parceljs.org/) + +.parcel-cache + +# Next.js build output + +.next +out + +# Nuxt.js build / generate output + +.nuxt +dist + +# Gatsby files + +# Comment in the public line in if your project uses Gatsby and not Next.js + +# https://nextjs.org/blog/next-9-1#public-directory-support + +# public + +# vuepress build output + +.vuepress/dist + +# vuepress v2.x temp and cache directory + +.temp + +# Docusaurus cache and generated files + +.docusaurus + +# Serverless directories + +.serverless/ + +# FuseBox cache + +.fusebox/ + +# DynamoDB Local files + +.dynamodb/ + +# TernJS port file + +.tern-port + +# Stores VSCode versions used for testing VSCode extensions + +.vscode-test + +# yarn v2 + +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* + +# IntelliJ based IDEs +.idea + +.cursor +!plugins/cursor/context7/.cursor +.opencode +.claude + +# Finder (MacOS) folder config +.DS_Store +package-lock.json + +prompt.txt + +reports +reports-old +src/test/questions* diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..7fd6ada --- /dev/null +++ b/.prettierignore @@ -0,0 +1,31 @@ +# Dependencies +node_modules + +# Lock files +pnpm-lock.yaml +package-lock.json +yarn.lock +bun.lockb + +# Build outputs +dist +build +.next +out + +# Logs +*.log + +# Environment files +.env +.env.* + +# IDE +.vscode +.idea + +# Changesets +.changeset/*.md + +# Documentation +docs diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..17900de --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2021 Upstash, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..8a01c35 --- /dev/null +++ b/README.md @@ -0,0 +1,163 @@ +![Cover](https://github.com/upstash/context7/blob/master/public/cover.png?raw=true) + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) + +# Context7 Platform - Up-to-date Code Docs For Any Prompt + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [![NPM Version](https://img.shields.io/npm/v/%40upstash%2Fcontext7-mcp?color=red)](https://www.npmjs.com/package/@upstash/context7-mcp) [![MIT licensed](https://img.shields.io/npm/l/%40upstash%2Fcontext7-mcp)](./LICENSE) + +[![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./i18n/README.zh-TW.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](./i18n/README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./i18n/README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./i18n/README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./i18n/README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./i18n/README.fr.md) [![Documentação em Português (Brasil)]()](./i18n/README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./i18n/README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./i18n/README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./i18n/README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./i18n/README.ru.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./i18n/README.uk.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./i18n/README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./i18n/README.ar.md) [![Tiếng Việt](https://img.shields.io/badge/docs-Tiếng%20Việt-red)](./i18n/README.vi.md) + +## ❌ Without Context7 + +LLMs rely on outdated or generic information about the libraries you use. You get: + +- ❌ Code examples are outdated and based on year-old training data +- ❌ Hallucinated APIs that don't even exist +- ❌ Generic answers for old package versions + +## ✅ With Context7 + +Context7 pulls up-to-date, version-specific documentation and code examples straight from the source — and places them directly into your prompt. + +```txt +Create a Next.js middleware that checks for a valid JWT in cookies +and redirects unauthenticated users to `/login`. use context7 +``` + +```txt +Configure a Cloudflare Worker script to cache +JSON API responses for five minutes. use context7 +``` + +```txt +Show me the Supabase auth API for email/password sign-up. +``` + +Context7 fetches up-to-date code examples and documentation right into your LLM's context. No tab-switching, no hallucinated APIs that don't exist, no outdated code generation. + +Works in two modes: + +- **CLI + Skills** — installs a skill that guides your agent to fetch docs using `ctx7` CLI commands (no MCP required) +- **MCP** — registers a Context7 MCP server so your agent can call documentation tools natively + +## Installation + +> [!NOTE] +> **API Key Recommended**: Get a free API key at [context7.com/dashboard](https://context7.com/dashboard) for higher rate limits. + +Set up Context7 for your coding agents with a single command. The `ctx7` CLI requires Node.js 18 or newer. + +```bash +npx ctx7 setup +``` + +Authenticates via OAuth, generates an API key, and installs the appropriate skill. You can choose between CLI + Skills or MCP mode. Use `--cursor`, `--claude`, or `--opencode` to target a specific agent. + +To remove the generated setup later, run `npx ctx7 remove`. If you globally installed the CLI with `npm install -g ctx7`, remove that package separately with `npm uninstall -g ctx7`. + +To configure manually, use the Context7 server URL `https://mcp.context7.com/mcp` with your MCP client and pass your API key via the `CONTEXT7_API_KEY` header. See the link below for client-specific setup instructions. + +**[Manual Installation / Other Clients →](https://context7.com/docs/resources/all-clients)** + +## Important Tips + +### Use Library Id + +If you already know exactly which library you want to use, add its Context7 ID to your prompt. That way, Context7 can skip the library-matching step and directly retrieve docs. + +```txt +Implement basic authentication with Supabase. use library /supabase/supabase for API and docs. +``` + +The slash syntax tells Context7 exactly which library to load docs for. + +### Specify a Version + +To get documentation for a specific library version, just mention the version in your prompt: + +```txt +How do I set up Next.js 14 middleware? use context7 +``` + +Context7 will automatically match the appropriate version. + +### Add a Rule + +If you installed via `ctx7 setup`, a skill is configured automatically that triggers Context7 for library-related questions. To set up a rule manually instead, add one to your coding agent: + +- **Cursor**: `Cursor Settings > Rules` +- **Claude Code**: `CLAUDE.md` +- Or the equivalent in your coding agent + +**Example rule:** + +```txt +Always use Context7 when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask. +``` + +## Available Tools + +### CLI Commands + +- `ctx7 library `: Searches the Context7 index by library name and returns matching libraries with their IDs. +- `ctx7 docs `: Retrieves documentation for a library using a Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`). + +### MCP Tools + +- `resolve-library-id`: Resolves a general library name into a Context7-compatible library ID. + - `query` (required): The user's question or task (used to rank results by relevance) + - `libraryName` (required): The name of the library to search for +- `query-docs`: Retrieves documentation for a library using a Context7-compatible library ID. + - `libraryId` (required): Exact Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`) + - `query` (required): The question or task to get relevant documentation for + +## More Documentation + +- [CLI Reference](https://context7.com/docs/clients/cli) - Full CLI documentation +- [MCP Clients](https://context7.com/docs/resources/all-clients) - Manual MCP installation for 30+ clients +- [Adding Libraries](https://context7.com/docs/adding-libraries) - Submit your library to Context7 +- [Troubleshooting](https://context7.com/docs/resources/troubleshooting) - Common issues and solutions +- [API Reference](https://context7.com/docs/api-guide) - REST API documentation +- [Developer Guide](https://context7.com/docs/resources/developer) - Run Context7 MCP locally + +## Packages + +- [`@upstash/context7-mcp`](https://www.npmjs.com/package/@upstash/context7-mcp) - MCP server +- [`ctx7`](https://www.npmjs.com/package/ctx7) - CLI +- [`@upstash/context7-sdk`](https://www.npmjs.com/package/@upstash/context7-sdk) - TypeScript SDK +- [`@upstash/context7-tools-ai-sdk`](https://www.npmjs.com/package/@upstash/context7-tools-ai-sdk) - Vercel AI SDK tools +- [`@upstash/context7-pi`](https://www.npmjs.com/package/@upstash/context7-pi) - pi.dev extension + +## Disclaimer + +1- Context7 projects are community-contributed and while we strive to maintain high quality, we cannot guarantee the accuracy, completeness, or security of all library documentation. Projects listed in Context7 are developed and maintained by their respective owners, not by Context7. If you encounter any suspicious, inappropriate, or potentially harmful content, please use the "Report" button on the project page to notify us immediately. We take all reports seriously and will review flagged content promptly to maintain the integrity and safety of our platform. By using Context7, you acknowledge that you do so at your own discretion and risk. + +2- This repository hosts the MCP server’s source code. The supporting components — API backend, parsing engine, and crawling engine — are private and not part of this repository. + +## 🤝 Connect with Us + +Stay updated and join our community: + +- 📢 Follow us on [X](https://x.com/context7ai) for the latest news and updates +- 🌐 Visit our [Website](https://context7.com) +- 💬 Join our [Discord Community](https://upstash.com/discord) + +## 📺 Context7 In Media + +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 License + +MIT diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..787832c --- /dev/null +++ b/README.wehub.md @@ -0,0 +1,7 @@ +# WeHub 来源说明 + +- 原始项目：`upstash/context7` +- 原始仓库：https://github.com/upstash/context7 +- 导入方式：上游默认分支的最新快照 +- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准 +- 本文件仅用于记录来源，不代表 WeHub 是原项目作者 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..2a16d1b --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,44 @@ +# Security Policy + +## Supported Versions + +The following versions of Context7 MCP are currently supported with security updates: + +| Version | Supported | +| ------- | ------------------ | +| 1.0.x | :white_check_mark: | + +We recommend always using the latest version (`@upstash/context7-mcp@latest`) to ensure you have the most recent security patches and features. + +## Reporting a Vulnerability + +We take the security of Context7 seriously. If you discover a security vulnerability, please report it responsibly. + +### How to Report + +- Please use GitHub's [private vulnerability reporting](https://github.com/upstash/context7/security/advisories/new) feature to submit your report +- Alternatively, you can email security concerns to [context7@upstash.com](mailto:context7@upstash.com) + +### What to Include + +- A description of the vulnerability +- Steps to reproduce the issue +- Potential impact of the vulnerability +- Any suggested fixes (optional) + +### What to Expect + +- **Initial Response**: We aim to acknowledge your report within 48 hours +- **Status Updates**: You can expect updates on the progress every 5-7 business days +- **Resolution Timeline**: We strive to resolve critical vulnerabilities within 30 days + +### After Reporting + +- If the vulnerability is accepted, we will work on a fix and coordinate disclosure with you +- We will credit reporters in our release notes (unless you prefer to remain anonymous) +- If the report is declined, we will provide an explanation + +### Please Do Not + +- Disclose the vulnerability publicly before we have addressed it +- Exploit the vulnerability beyond what is necessary to demonstrate it diff --git a/docs/adding-libraries.mdx b/docs/adding-libraries.mdx new file mode 100644 index 0000000..9520490 --- /dev/null +++ b/docs/adding-libraries.mdx @@ -0,0 +1,62 @@ +--- +title: Adding Libraries +description: Add a public library to Context7 so AI coding assistants get up-to-date docs for it +--- + +Context7 indexes public libraries from their source repositories so developers get current, version-specific documentation inside their coding tools. Anyone can add a public library — you don't need to own it. + +## Add a Library + +The fastest way to add a library is through the web interface: + +**[Add a Library →](https://context7.com/add-library)** + + + + Go to [context7.com/add-library](https://context7.com/add-library) and select the **GitHub** tab. + + + Paste the public GitHub repository URL for the library you want to add. + + + Optionally narrow what gets indexed by setting included folders and exclusions. For finer control — committed to the repository itself — add a `context7.json` file (see [Library Owners](/library-owners)). + + + Submit the repository. Context7 parses and indexes the documentation, then makes it available by its [library ID](/api-guide) (format: `/org/project`). + + + + + This page is for **public** libraries. To add internal or private documentation, see the [Private Sources](/howto/private-sources) guide (requires a Pro or Enterprise plan). + + +## What Gets Indexed + +Context7 parses documentation files — `.md`, `.mdx`, `.markdown`, `.rst`, `.txt`, and `.ipynb` — and extracts the code examples and explanations they contain. Raw source code files (`.py`, `.ts`, `.go`, and so on) are not indexed when documentation is present; a library's docs are expected to show the important usage examples. + +If a repository contains little or no documentation content, Context7 falls back to generating examples from the source code itself. For public repositories this fallback is automatic — there is no setting to turn it on or off. For [private repositories](/howto/private-sources), generating docs from source code is opt-in: check **Generate docs** when adding the source, or pass the `generateDocs` flag via the [API](/api-guide). + +To control which folders and files are scanned, set included folders when submitting, or commit a `context7.json` file to the repository (see [Library Owners](/library-owners)). + +## Maintain the Library? + +If you own or maintain the library, you can take control of how it appears in Context7 — configure parsing with `context7.json`, manage versions through a web admin panel, and get higher refresh limits. + + + + Control parsing and presentation with `context7.json` + + + Verify ownership and unlock the admin panel + + + +## Keeping Docs Fresh + +Once a library is added, Context7 [refreshes its documentation automatically](/library-updates) based on popularity, so developers keep receiving up-to-date docs without any manual work. + +For tighter control, add the [Context7 GitHub Action](/integrations/github-actions) to trigger a refresh on every push to your default branch — so a new release's docs are indexed as soon as you ship it. + +## Need Help? + +If you encounter issues or need assistance adding a library, please [open an issue](https://github.com/upstash/context7/issues/new/choose) or reach out to our community. diff --git a/docs/agentic-tools/ai-sdk/agents/context7-agent.mdx b/docs/agentic-tools/ai-sdk/agents/context7-agent.mdx new file mode 100644 index 0000000..7af48ab --- /dev/null +++ b/docs/agentic-tools/ai-sdk/agents/context7-agent.mdx @@ -0,0 +1,202 @@ +--- +title: "Context7Agent" +sidebarTitle: "Context7Agent" +description: "Pre-built AI agent for documentation lookup workflows" +--- + +The `Context7Agent` class is a pre-configured AI agent that handles the complete documentation lookup workflow automatically. It combines both `resolveLibraryId` and `queryDocs` tools with an optimized system prompt. + +## Usage + +```typescript +import { Context7Agent } from "@upstash/context7-tools-ai-sdk"; +import { anthropic } from "@ai-sdk/anthropic"; + +const agent = new Context7Agent({ + model: anthropic("claude-sonnet-4-20250514"), +}); + +const { text } = await agent.generate({ + prompt: "How do I use React Server Components?", +}); + +console.log(text); +``` + +## Configuration + +```typescript +new Context7Agent(config?: Context7AgentConfig) +``` + +### Parameters + + + Configuration options for the agent. + + + + Language model to use. Must be a LanguageModel instance from an AI SDK provider. + + Examples: + - `anthropic('claude-sonnet-4-20250514')` + - `openai('gpt-5.2')` + - `google('gemini-1.5-pro')` + + + Context7 API key. If not provided, uses the `CONTEXT7_API_KEY` environment variable. + + + Custom system prompt. Overrides the default `AGENT_PROMPT`. + + + Condition for when the agent should stop. Defaults to stopping after 5 steps. + + + + + +### Returns + +`Context7Agent` extends the AI SDK `Agent` class and provides `generate()` and `stream()` methods. + +## Agent Workflow + +The agent follows a structured multi-step workflow: + +```mermaid +flowchart TD + A[User Query] --> B[Extract Library Name] + B --> C[Call resolveLibraryId] + C --> D{Results Found?} + D -->|Yes| E[Select Best Match] + D -->|No| F[Report No Results] + E --> G[Call queryDocs] + G --> H{Sufficient Context?} + H -->|Yes| I[Generate Response] + H -->|No| J[Fetch More Docs] + J --> H + I --> K[Return Answer with Examples] +``` + +### Step-by-Step + +1. **Extract library name** - Identifies the library/framework from the user's query +2. **Resolve library** - Calls `resolveLibraryId` to find the Context7 library ID +3. **Select best match** - Analyzes results based on reputation, coverage, and relevance +4. **Fetch documentation** - Calls `queryDocs` with the selected library ID and user's query +5. **Query if needed** - Makes additional queries if initial context is insufficient +6. **Generate response** - Provides an answer with code examples from the documentation + +## Examples + +### Basic Usage + +```typescript +import { Context7Agent } from "@upstash/context7-tools-ai-sdk"; +import { anthropic } from "@ai-sdk/anthropic"; + +const agent = new Context7Agent({ + model: anthropic("claude-sonnet-4-20250514"), +}); + +const { text } = await agent.generate({ + prompt: "How do I set up authentication in Next.js?", +}); + +console.log(text); +``` + +### With OpenAI + +```typescript +import { Context7Agent } from "@upstash/context7-tools-ai-sdk"; +import { openai } from "@ai-sdk/openai"; + +const agent = new Context7Agent({ + model: openai("gpt-5.2"), +}); + +const { text } = await agent.generate({ + prompt: "Explain Tanstack Query's useQuery hook", +}); +``` + +### Streaming Responses + +```typescript +import { Context7Agent } from "@upstash/context7-tools-ai-sdk"; +import { anthropic } from "@ai-sdk/anthropic"; + +const agent = new Context7Agent({ + model: anthropic("claude-sonnet-4-20250514"), +}); + +const { textStream } = await agent.stream({ + prompt: "How do I create a Supabase Edge Function?", +}); + +for await (const chunk of textStream) { + process.stdout.write(chunk); +} +``` + +### Custom Configuration + +```typescript +import { Context7Agent } from "@upstash/context7-tools-ai-sdk"; +import { anthropic } from "@ai-sdk/anthropic"; +import { stepCountIs } from "ai"; + +const agent = new Context7Agent({ + model: anthropic("claude-sonnet-4-20250514"), + apiKey: process.env.CONTEXT7_API_KEY, + stopWhen: stepCountIs(8), // Allow more steps for complex queries +}); +``` + +### Custom System Prompt + +```typescript +import { Context7Agent, AGENT_PROMPT } from "@upstash/context7-tools-ai-sdk"; +import { openai } from "@ai-sdk/openai"; + +const agent = new Context7Agent({ + model: openai("gpt-5.2"), + system: `${AGENT_PROMPT} + +Additional instructions: +- Always include TypeScript examples +- Mention version compatibility when relevant +- Suggest related documentation topics`, +}); +``` + +## Comparison: Agent vs Tools + +| Feature | Context7Agent | Individual Tools | +| ------------- | -------------------- | -------------------- | +| Setup | Single configuration | Configure each tool | +| Workflow | Automatic multi-step | Manual orchestration | +| System prompt | Optimized default | You provide | +| Customization | Limited | Full control | +| Best for | Quick integration | Custom workflows | + +### When to Use the Agent + +- Rapid prototyping +- Standard documentation lookup use cases +- When you want sensible defaults + +### When to Use Individual Tools + +- Custom agentic workflows +- Integration with other tools +- Fine-grained control over the process +- Custom system prompts with specific behavior + +## Related + +- [resolveLibraryId](/agentic-tools/ai-sdk/tools/resolve-library-id) - The library search tool used by the agent +- [queryDocs](/agentic-tools/ai-sdk/tools/query-docs) - The documentation fetch tool used by the agent +- [Getting Started](/agentic-tools/ai-sdk/getting-started) - Overview of the AI SDK integration diff --git a/docs/agentic-tools/ai-sdk/getting-started.mdx b/docs/agentic-tools/ai-sdk/getting-started.mdx new file mode 100644 index 0000000..dc9c57f --- /dev/null +++ b/docs/agentic-tools/ai-sdk/getting-started.mdx @@ -0,0 +1,162 @@ +--- +title: "Getting Started" +sidebarTitle: "Getting Started" +description: "Add Context7 documentation tools to your Vercel AI SDK applications" +--- + +`@upstash/context7-tools-ai-sdk` provides [Vercel AI SDK](https://sdk.vercel.ai/) compatible tools and agents that give your AI applications access to up-to-date library documentation. + +When building AI-powered applications with the Vercel AI SDK, your models often need accurate information about libraries and frameworks. Instead of relying on potentially outdated training data, Context7 tools let your AI fetch current documentation on-demand, ensuring responses include correct API usage, current best practices, and working code examples. + +The package gives you two ways to integrate: + +1. **Individual tools** (`resolveLibraryId` and `queryDocs`) that you add to your existing `generateText` or `streamText` calls +2. **A pre-built agent** (`Context7Agent`) that handles the entire documentation lookup workflow automatically + +Both approaches work with any AI provider supported by the Vercel AI SDK, including OpenAI, Anthropic, Google, and others. + +## Installation + + +```bash npm +npm install @upstash/context7-tools-ai-sdk +``` + +```bash pnpm +pnpm add @upstash/context7-tools-ai-sdk +``` + +```bash yarn +yarn add @upstash/context7-tools-ai-sdk +``` + +```bash bun +bun add @upstash/context7-tools-ai-sdk +``` + + + +## Prerequisites + +You'll need: + +1. A Context7 API key from the [Context7 Dashboard](https://context7.com/dashboard) +2. An AI provider SDK (e.g., `@ai-sdk/openai`, `@ai-sdk/anthropic`) + +## Configuration + +Set your Context7 API key as an environment variable: + +```bash +CONTEXT7_API_KEY=ctx7sk-... +``` + +The tools and agents will automatically use this key. + +## Quick Start + +### Using Tools with generateText + +The simplest way to add documentation lookup to your AI application: + +```typescript +import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk"; +import { generateText, stepCountIs } from "ai"; +import { openai } from "@ai-sdk/openai"; + +const { text } = await generateText({ + model: openai("gpt-5.2"), + prompt: "How do I create a server action in Next.js?", + tools: { + resolveLibraryId: resolveLibraryId(), + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(5), +}); + +console.log(text); +``` + +### Using the Context7 Agent + +For a more streamlined experience, use the pre-configured agent: + +```typescript +import { Context7Agent } from "@upstash/context7-tools-ai-sdk"; +import { anthropic } from "@ai-sdk/anthropic"; + +const agent = new Context7Agent({ + model: anthropic("claude-sonnet-4-20250514"), +}); + +const { text } = await agent.generate({ + prompt: "How do I use React Server Components?", +}); + +console.log(text); +``` + +### Using Tools with streamText + +For streaming responses: + +```typescript +import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk"; +import { streamText, stepCountIs } from "ai"; +import { openai } from "@ai-sdk/openai"; + +const { textStream } = streamText({ + model: openai("gpt-5.2"), + prompt: "Explain how to use Tanstack Query for data fetching", + tools: { + resolveLibraryId: resolveLibraryId(), + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(5), +}); + +for await (const chunk of textStream) { + process.stdout.write(chunk); +} +``` + +## Explicit Configuration + +You can also pass the API key directly if needed: + +```typescript +import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk"; + +const tools = { + resolveLibraryId: resolveLibraryId({ apiKey: "your-api-key" }), + queryDocs: queryDocs({ apiKey: "your-api-key" }), +}; +``` + +## How It Works + +The tools follow a two-step workflow: + +1. **`resolveLibraryId`** - Searches Context7's database to find the correct library ID for a given query (e.g., "react" → `/reactjs/react.dev`) + +2. **`queryDocs`** - Fetches documentation for the resolved library using the user's query to retrieve relevant content + +The AI model orchestrates these tools automatically based on the user's prompt, fetching relevant documentation before generating a response. + +## Next Steps + + + + Search for libraries and get Context7-compatible IDs + + + Fetch documentation for a specific library + + + Use the pre-built documentation agent + + diff --git a/docs/agentic-tools/ai-sdk/tools/query-docs.mdx b/docs/agentic-tools/ai-sdk/tools/query-docs.mdx new file mode 100644 index 0000000..046315e --- /dev/null +++ b/docs/agentic-tools/ai-sdk/tools/query-docs.mdx @@ -0,0 +1,196 @@ +--- +title: "queryDocs" +sidebarTitle: "queryDocs" +description: "Fetch up-to-date documentation for a specific library" +--- + +The `queryDocs` tool fetches documentation for a library using its Context7-compatible library ID and a query. This tool is typically called after `resolveLibraryId` has identified the correct library. + +## Usage + +```typescript +import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk"; +import { generateText, stepCountIs } from "ai"; +import { openai } from "@ai-sdk/openai"; + +const { text } = await generateText({ + model: openai("gpt-5.2"), + prompt: "How do I use React Server Components?", + tools: { + resolveLibraryId: resolveLibraryId(), + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(5), +}); +``` + +## Configuration + +```typescript +queryDocs(config?: Context7ToolsConfig) +``` + +### Parameters + + + Configuration options for the tool. + + + + Context7 API key. If not provided, uses the `CONTEXT7_API_KEY` environment variable. + + + + +### Returns + +Returns an AI SDK `tool` that can be used with `generateText`, `streamText`, or agents. + +## Tool Behavior + +When the AI model calls this tool, it: + +1. Takes a library ID and query from the model +2. Fetches documentation from Context7's API +3. Returns the documentation content + +### Input Schema + +The tool accepts the following inputs from the AI model: + + + Context7-compatible library ID (e.g., `/reactjs/react.dev`, `/vercel/next.js`) + + + + The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: "How to set up authentication with JWT in Express.js" or "React useEffect cleanup function examples". Bad (too vague): "auth" or "hooks". Bad (too broad): "routing and auth and caching in Next.js". + + +### Output Format + +On success, the tool returns the documentation as plain text, formatted for easy consumption by the AI model: + +``` +# Server Components + +Server Components let you write UI that can be rendered and optionally cached on the server. + +## Example + +\`\`\`tsx +async function ServerComponent() { + const data = await fetchData(); + return
{data}
; +} +\`\`\` + +--- + +# Using Server Components with Client Components + +You can import Server Components into Client Components... +``` + +#### On Failure + +``` +No documentation found for library "/invalid/library". This might have happened because you used an invalid Context7-compatible library ID. Use 'resolveLibraryId' to get a valid ID. +``` + +## Examples + +### Basic Usage with Both Tools + +```typescript +import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk"; +import { generateText, stepCountIs } from "ai"; +import { openai } from "@ai-sdk/openai"; + +const { text } = await generateText({ + model: openai("gpt-5.2"), + prompt: "Show me how to set up routing in Next.js App Router", + tools: { + resolveLibraryId: resolveLibraryId(), + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(5), +}); + +// The model will: +// 1. Call resolveLibraryId to get the library ID +// 2. Call queryDocs({ libraryId: "/vercel/next.js", query: "routing in App Router" }) +// 3. Generate a response using the fetched documentation +``` + +### With Custom Configuration + +```typescript +import { queryDocs } from "@upstash/context7-tools-ai-sdk"; + +const tool = queryDocs({ + apiKey: process.env.CONTEXT7_API_KEY, +}); +``` + +### Direct Library ID (Skip resolveLibraryId) + +If the user provides a library ID directly, the model can skip the resolution step: + +```typescript +import { queryDocs } from "@upstash/context7-tools-ai-sdk"; +import { generateText, stepCountIs } from "ai"; +import { openai } from "@ai-sdk/openai"; + +const { text } = await generateText({ + model: openai("gpt-5.2"), + prompt: "Using /vercel/next.js, explain middleware", + tools: { + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(3), +}); + +// The model recognizes the /org/project format and calls queryDocs directly +``` + +### Multi-Step Documentation Lookup + +For comprehensive documentation, the model can make multiple queries: + +```typescript +import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk"; +import { generateText, stepCountIs } from "ai"; +import { anthropic } from "@ai-sdk/anthropic"; + +const { text } = await generateText({ + model: anthropic("claude-sonnet-4-20250514"), + prompt: "Give me a comprehensive guide to Supabase authentication", + tools: { + resolveLibraryId: resolveLibraryId(), + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(8), // Allow more steps for multiple queries +}); + +// The model may call queryDocs multiple times with different queries +// to gather comprehensive documentation +``` + +## Version-Specific Documentation + +Library IDs can include version specifiers: + +```typescript +// Latest version +"/vercel/next.js"; + +// Specific version +"/vercel/next.js/v14.3.0-canary.87"; +``` + +The model can request documentation for specific versions when the user asks about a particular version. + +## Related + +- [resolveLibraryId](/agentic-tools/ai-sdk/tools/resolve-library-id) - Search for libraries and get their IDs +- [Context7Agent](/agentic-tools/ai-sdk/agents/context7-agent) - Pre-built agent that handles the full workflow diff --git a/docs/agentic-tools/ai-sdk/tools/resolve-library-id.mdx b/docs/agentic-tools/ai-sdk/tools/resolve-library-id.mdx new file mode 100644 index 0000000..6f3492f --- /dev/null +++ b/docs/agentic-tools/ai-sdk/tools/resolve-library-id.mdx @@ -0,0 +1,174 @@ +--- +title: "resolveLibraryId" +sidebarTitle: "resolveLibraryId" +description: "Search for libraries and resolve them to Context7-compatible IDs" +--- + +The `resolveLibraryId` tool searches Context7's library database and returns matching results with their Context7-compatible library IDs. This is typically the first step in a documentation lookup workflow. + +## Usage + +```typescript +import { resolveLibraryId } from "@upstash/context7-tools-ai-sdk"; +import { generateText, stepCountIs } from "ai"; +import { openai } from "@ai-sdk/openai"; + +const { text } = await generateText({ + model: openai("gpt-5.2"), + prompt: "Find documentation for React hooks", + tools: { + resolveLibraryId: resolveLibraryId(), + }, + stopWhen: stepCountIs(3), +}); +``` + +## Configuration + +```typescript +resolveLibraryId(config?: Context7ToolsConfig) +``` + +### Parameters + + + Configuration options for the tool. + + + + Context7 API key. If not provided, uses the `CONTEXT7_API_KEY` environment variable. + + + + +### Returns + +Returns an AI SDK `tool` that can be used with `generateText`, `streamText`, or agents. + +## Tool Behavior + +When the AI model calls this tool, it: + +1. Takes a `query` and `libraryName` parameter from the model +2. Searches Context7's database for matching libraries +3. Returns formatted results including: + - Library ID (e.g., `/reactjs/react.dev`) + - Title and description + - Number of code snippets available + - Source reputation score + - Available versions + +### Input Schema + +The tool accepts the following input from the AI model: + + + The user's original question or task. This is used to rank library results by relevance to what the user is trying to accomplish. + + + + Library name to search for (e.g., "react", "next.js", "vue") + + +### Output Format + +On success, the tool returns the search results as plain text, formatted for easy consumption by the AI model: + +``` +- Title: React Documentation +- Context7-compatible library ID: /reactjs/react.dev +- Description: The library for web and native user interfaces +- Code Snippets: 1250 +- Source Reputation: High +- Benchmark Score: 98 +- Versions: 19.0.0, 18.3.1, 18.2.0 +---------- +- Title: React Native +- Context7-compatible library ID: /facebook/react-native +- Description: A framework for building native applications using React +- Code Snippets: 890 +- Source Reputation: High +- Benchmark Score: 95 +- Versions: 0.76.0, 0.75.4 +``` + +On failure: + +``` +No libraries found matching "unknown-lib". Try a different search term or check the library name. +``` + +## Examples + +### Basic Usage + +```typescript +import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk"; +import { generateText, stepCountIs } from "ai"; +import { openai } from "@ai-sdk/openai"; + +const { text, toolCalls } = await generateText({ + model: openai("gpt-5.2"), + prompt: "What libraries are available for React?", + tools: { + resolveLibraryId: resolveLibraryId(), + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(5), +}); + +// The model will call resolveLibraryId and receive a list of matching libraries +console.log(text); +``` + +### With Custom API Key + +```typescript +import { resolveLibraryId } from "@upstash/context7-tools-ai-sdk"; + +const tool = resolveLibraryId({ + apiKey: process.env.CONTEXT7_API_KEY, +}); +``` + +### Inspecting Tool Calls + +```typescript +import { resolveLibraryId } from "@upstash/context7-tools-ai-sdk"; +import { generateText, stepCountIs } from "ai"; +import { openai } from "@ai-sdk/openai"; + +const { toolCalls, toolResults } = await generateText({ + model: openai("gpt-5.2"), + prompt: "Find the official Next.js documentation", + tools: { + resolveLibraryId: resolveLibraryId(), + }, + stopWhen: stepCountIs(3), +}); + +// See what the model searched for +for (const call of toolCalls) { + console.log("Searched for:", call.input.libraryName); +} + +// See the results +for (const result of toolResults) { + console.log("Found:", result.output); +} +``` + +## Selection Guidance + +The tool's description instructs the AI model to select libraries based on: + +1. **Name similarity** - Exact matches are prioritized +2. **Description relevance** - How well the description matches the query intent +3. **Documentation coverage** - Libraries with more code snippets are preferred +4. **Source reputation** - High/Medium reputation sources are more authoritative +5. **Benchmark score** - Quality indicator (100 is the highest) + +## Related + +- [queryDocs](/agentic-tools/ai-sdk/tools/query-docs) - Fetch documentation using the resolved library ID +- [Context7Agent](/agentic-tools/ai-sdk/agents/context7-agent) - Pre-built agent that handles the full workflow diff --git a/docs/agentic-tools/overview.mdx b/docs/agentic-tools/overview.mdx new file mode 100644 index 0000000..3c8c662 --- /dev/null +++ b/docs/agentic-tools/overview.mdx @@ -0,0 +1,139 @@ +--- +title: "Overview" +sidebarTitle: "Overview" +description: "Build AI agents with up-to-date library documentation" +--- + +# Agentic Tools + +Context7 provides tools and integrations that give your AI agents access to accurate, up-to-date library documentation. Instead of relying on potentially outdated training data, your agents can fetch real-time documentation to answer questions and generate code. + +## Why Agentic Tools? + +AI agents often struggle with: + +- **Outdated knowledge** - Training data becomes stale, leading to deprecated API usage +- **Hallucinated APIs** - Models confidently suggest methods that don't exist +- **Version mismatches** - Code examples from old versions that no longer work + +Context7's agentic tools solve these problems by giving your agents direct access to current documentation during inference. + +## Available Integrations + + + + Add Context7 tools to your AI SDK workflows with `generateText`, `streamText`, or use the + pre-built `Context7Agent` for automatic documentation lookup. + + + Call Context7 directly from any TypeScript or Node.js app. + + + Connect Context7's MCP server to any agent or editor. + + + +## How It Works + +```mermaid +sequenceDiagram + participant User + participant Agent + participant Context7 + participant Docs + + User->>Agent: "How do I use React Server Components?" + Agent->>Context7: resolveLibraryId(query: "React Server Components", libraryName: "react") + Context7-->>Agent: Library ID: /reactjs/react.dev + Agent->>Context7: queryDocs(libraryId: "/reactjs/react.dev", query: "server components") + Context7->>Docs: Fetch latest documentation + Docs-->>Context7: Current docs with examples + Context7-->>Agent: Documentation content + Agent->>User: Answer with accurate, up-to-date code examples +``` + +## Use Cases + + + + Build chatbots that answer framework questions with accurate, version-specific information: + + ```typescript + import { generateText, stepCountIs } from "ai"; + import { openai } from "@ai-sdk/openai"; + import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk"; + + const { text } = await generateText({ + model: openai("gpt-5.2"), + prompt: "How do I set up authentication in Next.js 15?", + tools: { + resolveLibraryId: resolveLibraryId(), + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(5), + }); + ``` + + + + + Ensure generated code uses current APIs and best practices: + + ```typescript + import { Context7Agent } from "@upstash/context7-tools-ai-sdk"; + import { anthropic } from "@ai-sdk/anthropic"; + + const agent = new Context7Agent({ + model: anthropic("claude-sonnet-4-20250514"), + }); + + const { text } = await agent.generate({ + prompt: "Generate a Supabase Edge Function that handles webhooks", + }); + ``` + + + + + Build code review agents that verify implementations against current API documentation: + + ```typescript + import { generateText, stepCountIs } from "ai"; + import { anthropic } from "@ai-sdk/anthropic"; + import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk"; + + const codeToReview = ` + const { data } = await supabase + .from('users') + .select('*') + .eq('id', userId) + .single(); + `; + + const { text } = await generateText({ + model: anthropic("claude-sonnet-4-20250514"), + prompt: `Review this Supabase code for correctness and best practices: + + ${codeToReview} + + Check against the latest Supabase documentation.`, + tools: { + resolveLibraryId: resolveLibraryId(), + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(5), + }); + + // Agent fetches current Supabase docs to verify: + // - Correct method signatures + // - Deprecated patterns + // - Security best practices + // - Error handling recommendations + ``` + + + diff --git a/docs/api-guide.mdx b/docs/api-guide.mdx new file mode 100644 index 0000000..1be3de0 --- /dev/null +++ b/docs/api-guide.mdx @@ -0,0 +1,204 @@ +--- +title: API Guide +description: Authentication, rate limits, best practices, and integration guides for the Context7 API +--- + +## Authentication + +All API requests require authentication using an API key. Include your API key in the `Authorization` header: + +```bash +Authorization: Bearer CONTEXT7_API_KEY +``` + +Get your API key at [context7.com/dashboard](https://context7.com/dashboard). Learn more about [creating and managing API keys](/howto/api-keys). + + +## API Methods + +| Method | Endpoint | Description | +|--------|----------|-------------| +| [Search Library](/api-reference/search/search-for-libraries) | `GET /api/v2/libs/search` | Find libraries by name | +| [Get Context](/api-reference/context/get-documentation-context) | `GET /api/v2/context` | Retrieve documentation snippets for a library | +| [Refresh Library](/api-reference/refresh/refresh-a-library) | `POST /api/v1/refresh` | Refresh a library's documentation | +| [Get Policies](/api-reference/policies/get-teamspace-policies) | `GET /api/v2/policies` | Retrieve teamspace policy configuration | +| [Update Policies](/api-reference/policies/update-teamspace-policies) | `PATCH /api/v2/policies` | Update teamspace policies | +| [Add Library](/api-reference/add-library/add-a-github-repository) | `POST /api/v2/add/repo/{provider}` | Submit a repository for processing | +| [Add OpenAPI](/api-reference/add-library/add-an-openapi-specification-by-url) | `POST /api/v2/add/openapi` | Submit an OpenAPI spec | +| [Upload OpenAPI](/api-reference/add-library/upload-an-openapi-specification-file) | `POST /api/v2/add/openapi-upload` | Upload an OpenAPI spec file | +| [Add LLMs.txt](/api-reference/add-library/add-an-llmstxt-file) | `POST /api/v2/add/llmstxt` | Submit an llms.txt file | +| [Add Website](/api-reference/add-library/add-a-website) | `POST /api/v2/add/website` | Submit a website for crawling | +| [Add Confluence](/api-reference/add-library/add-a-confluence-space) | `POST /api/v2/add/confluence` | Submit a Confluence space | + +## Library ID format + +A **library ID** is the URL path of the library on context7.com. If the library page is at `https://context7.com/websites/uploadcare_com`, its ID is `/websites/uploadcare_com`. The same ID works for every endpoint that accepts a `libraryId` or `libraryName` — including [Get Context](/api-reference/context/get-documentation-context) and [Refresh Library](/api-reference/refresh/refresh-a-library). + +Use `/owner/repo` for GitHub repositories, or `//` for other sources: + +| Source | Example library ID | +|--------|--------------------| +| GitHub repository | `/vercel/next.js` | +| GitLab / Bitbucket / generic Git repo | `//` (same shape as GitHub) | +| Website | `/websites/uploadcare_com` | +| llms.txt source | `/llmstxt/` | +| npm / package source | `/packages/` or `/npm/` | +| Uploaded docs | `/docs/` | + +You can pin a specific version with either `/owner/repo/` or `/owner/repo@`: + +``` +/vercel/next.js/v15.1.8 +/vercel/next.js@v15.1.8 +``` + + + Don't know the ID for a library? Find it on [context7.com](https://context7.com) — the URL path of the library page **is** the ID. Or call [Search Library](/api-reference/search/search-for-libraries) and use the `id` from the response. + + +### Complete Workflow Example + +```python +import os +import requests + +headers = {"Authorization": f"Bearer {os.environ['CONTEXT7_API_KEY']}"} + +# Step 1: Search for the library +search_response = requests.get( + "https://context7.com/api/v2/libs/search", + headers=headers, + params={"libraryName": "react", "query": "I need to manage state"} +) +data = search_response.json() +best_match = data["results"][0] +print(f"Found: {best_match['title']} ({best_match['id']})") + +# Step 2: Get documentation context +context_response = requests.get( + "https://context7.com/api/v2/context", + headers=headers, + params={"libraryId": best_match["id"], "query": "How do I use useState?", "type": "json"} +) +docs = context_response.json() + +for snippet in docs["codeSnippets"]: + print(f"Title: {snippet['codeTitle']}") + for code in snippet["codeList"]: + print(f"Code: {code['code'][:200]}...") + +for info in docs["infoSnippets"]: + print(f"Content: {info['content'][:200]}...") +``` + + + For TypeScript SDK usage, see [Search Library](/sdks/ts/commands/search-library) and [Get Context](/sdks/ts/commands/get-context). + + +## Rate Limits + +- **Without API key**: Low rate limits and no custom configuration +- **With API key**: Higher limits based on your plan +- View current usage and reset windows in the [dashboard](https://context7.com/dashboard). + +When you exceed rate limits, the API returns a `429` status code with these headers: + +| Header | Description | +|--------|-------------| +| `Retry-After` | Seconds until rate limit resets | +| `RateLimit-Limit` | Total request limit | +| `RateLimit-Remaining` | Remaining requests in window | +| `RateLimit-Reset` | Unix timestamp when limit resets | + +## Best Practices + +### Be Specific with Queries + +Use detailed, natural language queries for better results: + +```bash +# Good - specific question +curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=How%20to%20implement%20authentication%20with%20middleware" \ + -H "Authorization: Bearer CONTEXT7_API_KEY" + +# Less optimal - vague query +curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=auth" \ + -H "Authorization: Bearer CONTEXT7_API_KEY" + +# Non-GitHub source (website) - same endpoint, same shape +curl "https://context7.com/api/v2/context?libraryId=/websites/uploadcare_com&query=image%20transformations" \ + -H "Authorization: Bearer CONTEXT7_API_KEY" +``` + +### Cache Responses + +Documentation updates are relatively infrequent, so caching responses for several hours or days reduces API calls and improves performance. + +### Handle Rate Limits + +Implement exponential backoff for rate limit errors: + +```python +import time +import requests + +def fetch_with_retry(url, headers, max_retries=3): + for attempt in range(max_retries): + response = requests.get(url, headers=headers) + + if response.status_code == 429: + retry_after = int(response.headers.get("Retry-After", 2 ** attempt)) + time.sleep(retry_after) + continue + + return response + + raise Exception("Max retries exceeded") +``` + +### Use Specific Versions + +Pin to a specific version for consistent results. Both `/` and `@` syntax are supported: + +```bash +curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js/v15.1.8&query=app%20router" \ + -H "Authorization: Bearer CONTEXT7_API_KEY" + +curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js@v15.1.8&query=app%20router" \ + -H "Authorization: Bearer CONTEXT7_API_KEY" +``` + +## Error Handling + +The Context7 API uses standard HTTP status codes: + +| Code | Description | Action | +| ---- | ----------------------------------------- | -------------------------------------------- | +| 200 | Success | Process the response normally | +| 202 | Accepted - Library not finalized | Wait and retry later | +| 301 | Moved - Library redirected | Use the new library ID from `redirectUrl` | +| 400 | Bad Request - Invalid parameters | Check query parameters | +| 401 | Unauthorized - Invalid API key | Check your API key format (starts with `ctx7sk`) | +| 403 | Forbidden - Access denied | Check library access permissions or plan | +| 404 | Not Found - Library doesn't exist | Verify the library ID | +| 409 | Conflict - Resource already exists | The library has already been added | +| 422 | Unprocessable - Library too large/no code | Try a different library | +| 429 | Too Many Requests - Rate limit exceeded | Wait for `Retry-After` header, then retry | +| 500 | Internal Server Error | Retry with backoff | +| 503 | Service Unavailable - Search failed | Retry later | +| 504 | Gateway Timeout - Processing timed out | Retry later | + +All errors return a JSON object with `error` and `message` fields: + +```json +{ + "error": "library_not_found", + "message": "Library \"/owner/repo\" not found. Please check the library ID or your access permissions." +} +``` + +For `301` redirects, the response also includes a `redirectUrl` field pointing to the new library ID. + +## SDK and Libraries + +For TypeScript SDK installation and usage, see the [Getting Started guide](/sdks/ts/getting-started). diff --git a/docs/clients/claude-code.mdx b/docs/clients/claude-code.mdx new file mode 100644 index 0000000..277b998 --- /dev/null +++ b/docs/clients/claude-code.mdx @@ -0,0 +1,178 @@ +--- +title: Claude Code +description: Using Context7 with Claude Code +--- + +Context7 integrates with Claude Code to provide current library documentation instead of relying on training data. Claude Code supports skills, agents, and commands that make documentation lookups more powerful. + +## Installation + +Run the setup command to configure Context7 for Claude Code: + +```bash +npx ctx7 setup --claude +``` + +This flow authenticates via OAuth, generates an API key, and installs the appropriate skill. You can choose between CLI or MCP mode. Login uses the OAuth device flow — it shows a verification link and short code you open on any device, so it works the same locally or on a remote, headless, or SSH host. + +Create or manage API keys in the [Context7 dashboard](https://context7.com/dashboard). For manual MCP installation or other configuration options, see [All MCP Clients](/resources/all-clients). + +--- + +## Using Context7 + +With `ctx7 setup`, a skill is installed that triggers automatically when you ask about libraries — no need to say "use context7". You can also invoke it explicitly: + +``` +use context7 to show me how to set up middleware in Next.js 15 +use context7 for Prisma query examples with relations +use context7 for the Supabase syntax for row-level security +``` + +If you know the library ID, use it directly to skip resolution: + +``` +use context7 with /supabase/supabase for authentication docs +use context7 with /vercel/next.js for app router setup +``` + + +With the [Context7 plugin](#the-context7-plugin) installed, you get additional agents and commands on top of the skill. + + +--- + +## The Context7 Plugin + +The full Context7 plugin for Claude Code includes more than just the MCP server: + + + +The tools for fetching documentation (`resolve-library-id`, `query-docs`) + + +Auto-triggers documentation lookups when you ask about libraries + + +A `docs-researcher` agent for focused lookups that keep context lean + + +`/context7:docs` for manual documentation queries + + + +### Installing the Plugin + +The plugin is available from the Context7 marketplace. Run these commands in Claude Code: + +``` +/plugin marketplace add upstash/context7 +/plugin install context7@context7-marketplace +``` + +This adds the Context7 marketplace and installs the plugin with skills, agents, and commands. + +### Using Your API Key with the Plugin + +Without an API key, the plugin connects anonymously and shares the anonymous rate limits. To use your own plan, create an API key in the [Context7 dashboard](https://context7.com/dashboard) and export it as an environment variable before launching Claude Code: + +```bash +# e.g. in ~/.zshrc or ~/.bashrc +export CONTEXT7_API_KEY="your-api-key" +``` + +The plugin reads `CONTEXT7_API_KEY` from your environment automatically. Restart Claude Code after setting it, then confirm requests are counted against your plan in the [dashboard](https://context7.com/dashboard). + + +If the variable is not set, the plugin still works — requests just go through the anonymous tier, which has lower rate limits. + + +### Skills + +#### Documentation Lookup Skill + +This skill triggers automatically when you ask about libraries, frameworks, or need code examples. You don't need to type "use context7" — the skill recognizes when documentation would help. + + + +- Setup questions: "How do I configure Next.js middleware?" +- Code generation: "Write a Prisma query for user relations" +- API references: "What are the Supabase auth methods?" +- Framework mentions: React, Vue, Svelte, Express, Tailwind, etc. + + +1. **Resolve**: Finds the library ID using `resolve-library-id` with your question as context +2. **Select**: Picks the best match based on name accuracy and quality scores +3. **Fetch**: Calls `query-docs` with the library ID and your specific question +4. **Return**: Provides code examples and explanations from current documentation + + + +### Agents + +#### docs-researcher Agent + +When you're in the middle of a long task and don't want documentation tool calls cluttering your context, spawn the `docs-researcher` agent. It runs in a separate context and returns just the answer. + + + +- You need docs but want to keep your main context clean +- You're working on something complex and context is getting long +- You want a focused answer without side effects + + +``` +spawn docs-researcher to look up React hooks documentation +spawn docs-researcher: how do I set up Prisma with PostgreSQL? +spawn docs-researcher to find Tailwind CSS grid utilities +``` + + + +The agent uses the same tools (`resolve-library-id` and `query-docs`) but runs on a lighter model (Sonnet) to keep things fast. + +#### When to Use Agents vs Inline Tools + +| Scenario | Use | +|----------|-----| +| Deep into a task with long context | Agent | +| Want to avoid context bloat | Agent | +| Context is short | Inline tools | +| Want docs visible in conversation | Inline tools | + +### Commands + +#### /context7:docs + +Manual command for documentation lookups. + +**Format:** +``` +/context7:docs [query] +``` + +**Examples:** + + + +``` +/context7:docs react hooks +/context7:docs next.js authentication +/context7:docs prisma relations +``` + + +``` +/context7:docs /vercel/next.js app router +/context7:docs /supabase/supabase row level security +``` + +Using a library ID directly skips the resolution step. + + + +**When to use:** +- You know exactly which library and topic you need +- You want a quick lookup without explaining your full context +- You're testing what documentation is available + diff --git a/docs/clients/cli.mdx b/docs/clients/cli.mdx new file mode 100644 index 0000000..6124f65 --- /dev/null +++ b/docs/clients/cli.mdx @@ -0,0 +1,251 @@ +--- +title: CLI +description: The ctx7 CLI — fetch library documentation and configure Context7 MCP from your terminal +--- + +The `ctx7` CLI is the command-line interface for Context7. It does two things: + +- **Fetch library documentation** — resolve any library by name and query its up-to-date docs directly in your terminal, without opening a browser +- **Configure your AI coding agent** — set up the Context7 MCP server (or a CLI-based `docs` skill) for Claude Code, Cursor, OpenCode, and more with a single command + +The CLI is useful both as a standalone tool (fetching docs while you code) and as a setup utility (wiring up Context7 for your AI coding agent). + +## Installation + +Requires Node.js 18 or later. + + + + Run ctx7 directly without installing anything. Useful for one-off commands or trying it out. + + ```bash + npx ctx7 --help + npx ctx7 library react + ``` + + + + Install globally for faster access — no `npx` prefix needed on every command. + + ```bash + npm install -g ctx7 + + # Verify installation + ctx7 --version + ``` + + + + +--- + +## Query Library Documentation + +Fetching docs is a two-step process: first resolve the library name to get its Context7 ID, then use that ID to query documentation. + +### Step 1 — ctx7 library + +Searches the Context7 index by name and returns matching libraries. Pass a `query` describing what you're trying to do — this ranks results by relevance and helps when a library name is ambiguous or shared across multiple packages. + +```bash +ctx7 library react "How to clean up useEffect with async operations" +ctx7 library nextjs "How to set up app router with middleware" +ctx7 library prisma "How to define one-to-many relations with cascade delete" +``` + +Each result includes: + +| Field | Description | +| --------------------- | -------------------------------------------------------------------------- | +| **Library ID** | The identifier to pass to `ctx7 docs` (format: `/org/project`) | +| **Code Snippets** | Number of indexed code examples — higher means more documentation coverage | +| **Source Reputation** | Authority indicator: High, Medium, Low, or Unknown | +| **Benchmark Score** | Quality score from 0 to 100 | +| **Versions** | Version-specific IDs when available (format: `/org/project/version`) | + +When multiple results come back, the best match is usually the one with the closest name, highest snippet count, and strongest reputation. If you need docs for a specific version, pick the matching version ID from the list. + +```bash +# Fetch docs for a specific version +ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router" + +# Output as JSON for scripting +ctx7 library react "How to use hooks for state management" --json | jq '.[0].id' +``` + +### Step 2 — ctx7 docs + +Takes a library ID and a natural-language question, and returns relevant code snippets and explanations from the indexed documentation. + +```bash +ctx7 docs /facebook/react "How to clean up useEffect with async operations" +ctx7 docs /vercel/next.js "How to add middleware that redirects unauthenticated users" +ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete" +``` + + + Library IDs always start with `/`. Running `ctx7 docs react "hooks"` will fail — always use the + full ID returned by `ctx7 library` in Step 1. + + +Queries work best when they're specific. Describe what you're trying to accomplish rather than using single keywords — `"How to set up authentication with JWT in Express.js"` returns much better results than `"auth"`. + +The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context). Both are formatted for readability in the terminal. + +```bash +# Output as structured JSON +ctx7 docs /facebook/react "How to use hooks for state management" --json + +# Pipe to other tools — output is clean when not in a TTY (no spinners or colors) +ctx7 docs /facebook/react "How to use hooks for state management" | head -50 +ctx7 docs /vercel/next.js "How to add middleware for route protection" | grep -A 10 "middleware" +``` + +--- + +## Setup + +Configure Context7 for your AI coding agent. On first run, prompts you to choose between two modes: + +- **MCP server** — registers the Context7 MCP server in your agent's config so it can call `resolve-library-id` and `query-docs` tools natively +- **CLI + Skills** — installs a `docs` skill that guides your agent to fetch up-to-date library docs using `ctx7` CLI commands (no MCP required) + +### ctx7 setup + +```bash +# Interactive — prompts for mode, then agent/install target +ctx7 setup + +# Skip the mode prompt +ctx7 setup --mcp # MCP server mode +ctx7 setup --cli # CLI + Skills mode + +# Target a specific agent (MCP mode) +ctx7 setup --claude +ctx7 setup --cursor +ctx7 setup --opencode + +# Target a specific install location (CLI + Skills mode) +ctx7 setup --cli --claude # Claude Code (~/.claude/skills) +ctx7 setup --cli --cursor # Cursor (~/.cursor/skills) +ctx7 setup --cli --universal # Universal (~/.agents/skills) +ctx7 setup --cli --antigravity # Antigravity (~/.agent/skills) + +# Configure for current project only (default is global) +ctx7 setup --project + +# Skip confirmation prompts +ctx7 setup --yes +``` + +**Authentication options:** + +```bash +# Use an existing API key (works for both MCP and CLI + Skills mode) +ctx7 setup --api-key YOUR_API_KEY + +# Use OAuth endpoint — MCP mode only (IDE handles the auth flow) +ctx7 setup --oauth +``` + +Without `--api-key` or `--oauth`, setup runs the OAuth device flow: it shows a verification link and short code that you open on any device to sign in, so it works the same locally or on a remote, headless, or SSH host. MCP mode additionally generates a new API key after login. `--oauth` is MCP-only — use it when an IDE handles the auth flow on your behalf. + +**What gets written — MCP mode:** + +| File | Purpose | +| --------------------------------------------------- | ---------------------------------------------------------------- | +| `.mcp.json` / `.cursor/mcp.json` / `.opencode.json` | MCP server entry | +| Agent rules directory | Rule file — instructs the agent to use Context7 for library docs | +| Agent skills directory | `context7-mcp` skill | + +**What gets written — CLI + Skills mode:** + +| File | Purpose | +| ---------------------- | ------------------------------------------------------------------------------ | +| Agent skills directory | `docs` skill — guides the agent to use `ctx7 library` and `ctx7 docs` commands | + +### ctx7 remove + +Remove the setup written by `ctx7 setup`. By default this removes both MCP setup and CLI setup for the selected agent. + +```bash +# Interactive +ctx7 remove + +# Target specific agents +ctx7 remove --cursor +ctx7 remove --claude --project + +# Remove both setup modes explicitly +ctx7 remove --cursor --all + +# Remove only one setup mode +ctx7 remove --cursor --cli +ctx7 remove --claude --mcp +``` + +If you installed the CLI itself with `npm install -g ctx7`, remove that separately with `npm uninstall -g ctx7`. If you run Context7 with `npx ctx7`, there is no permanent CLI install to remove. + +--- + +## Authentication + +Most commands work without authentication. Log in to unlock higher rate limits on documentation commands. + +### Commands + +```bash +# Log in (opens browser for OAuth) +ctx7 login + +# Log in without opening the browser (prints URL instead) +ctx7 login --no-browser + +# Check current login status +ctx7 whoami + +# Log out +ctx7 logout +``` + +### API Key + +Set an API key via environment variable to skip interactive login entirely — useful for CI or scripting: + +```bash +export CONTEXT7_API_KEY=your_key +``` + +### When is authentication required? + +| Feature | Required | +| -------------------------------------------------------- | ---------------------------------------------------------------------------- | +| `ctx7 library` / `ctx7 docs` | No — login gives higher rate limits | +| `ctx7 setup` | Yes — unless `--api-key` is passed (`--oauth` also skips login for MCP mode) | + +--- + +## Telemetry + +The CLI collects anonymous usage data to help improve the product. To disable: + +```bash +# For a single command +CTX7_TELEMETRY_DISABLED=1 ctx7 docs /facebook/react "useEffect examples" + +# Permanently — add to ~/.bashrc or ~/.zshrc +export CTX7_TELEMETRY_DISABLED=1 +``` + +--- + +## Next Steps + + + + Set up Context7 in Claude Code + + + Installation for every supported editor + + diff --git a/docs/clients/codex.mdx b/docs/clients/codex.mdx new file mode 100644 index 0000000..58383db --- /dev/null +++ b/docs/clients/codex.mdx @@ -0,0 +1,129 @@ +--- +title: Codex +description: Using Context7 with OpenAI Codex +--- + +Context7 integrates with [OpenAI Codex](https://developers.openai.com/codex/) to provide current library documentation instead of relying on training data. Codex comes in three surfaces — the Codex CLI, Codex Desktop, and Codex Cloud — and Context7 works across all of them. + + +MCP servers in Codex are configured once and shared everywhere. The Codex CLI, Codex Desktop, and the IDE extension all read the same `~/.codex/config.toml`, so adding Context7 in one place enables it in the others. See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details. + + +## Installation + +Run the setup command to configure Context7 for Codex: + +```bash +npx ctx7 setup --codex +``` + +This authenticates via OAuth, generates an API key, and writes the Context7 configuration to your `~/.codex/config.toml` and `AGENTS.md`. You can choose between CLI or MCP mode. Login uses the OAuth device flow, which shows a verification link and short code you open on any device, so it works locally, on SSH hosts, and in headless environments. + +You can also install Context7 as a Codex plugin. It connects to the hosted MCP server and includes a skill that looks up documentation when you ask about libraries: + +```bash +codex plugin marketplace add upstash/context7 +codex plugin add context7@context7-marketplace +``` + +After adding the plugin, a browser window opens so you can log in to Context7 via OAuth — plugin installs use your account's authenticated rate limits too. Start a new Codex thread after installation so Codex can load the plugin's skill and MCP tools. + +Create or manage API keys in the [Context7 dashboard](https://context7.com/dashboard). For manual configuration or other clients, see [All MCP Clients](/resources/all-clients). + +--- + +## Codex surfaces + + + +The local coding agent that runs in your terminal. Add Context7 with `codex mcp add` or by editing `config.toml`. + + +The Codex app for macOS and Windows. Enable Context7 from the app's MCP settings, or rely on the shared `config.toml`. + + +The web-based agent that runs tasks in cloud environments. Add Context7 to the tools for an environment from the Codex web app. + + + +### Codex CLI + +If you only want the MCP server, add Context7 from the terminal with the `codex mcp add` command: + +```bash +codex mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY +``` + +Or add it directly to `~/.codex/config.toml` (use a project-scoped `.codex/config.toml` for trusted projects): + +```toml +[mcp_servers.context7] +command = "npx" +args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] +startup_timeout_ms = 20_000 +``` + +Prefer the hosted server? Use the remote connection instead: + +```toml +[mcp_servers.context7] +url = "https://mcp.context7.com/mcp" +http_headers = { "CONTEXT7_API_KEY" = "YOUR_API_KEY" } +``` + +### Codex Desktop + +The Codex app (macOS and Windows) shares the same MCP configuration as the CLI and IDE extension. Enable Context7 from the app's MCP settings, or add it to `~/.codex/config.toml` using the snippets above — it's picked up automatically. + +### Codex Cloud + +Codex Cloud delegates tasks to OpenAI's agent in managed cloud environments, so they can run in the background without your local machine. Each environment defines the repo, setup steps, and tools Codex uses — configure Context7 as part of an [environment](https://developers.openai.com/codex/cloud/environments) from the Codex web app. Cloud environments also have [configurable internet access](https://developers.openai.com/codex/cloud/internet-access), which Context7 needs to reach the documentation API. + +--- + +## Using Context7 + +With `ctx7 setup` or the plugin, a skill triggers automatically when you ask about libraries. You can also invoke it explicitly: + +``` +use context7 to show me how to set up middleware in Next.js 15 +use context7 for Prisma query examples with relations +use context7 for the Supabase syntax for row-level security +``` + +If you know the library ID, use it directly to skip resolution: + +``` +use context7 with /supabase/supabase for authentication docs +use context7 with /vercel/next.js for app router setup +``` + +You can also add instructions to your `AGENTS.md` file: + +```markdown AGENTS.md +When you need to search docs, use Context7. +``` + +--- + +## Tips + + + +- Be specific about what you're trying to do, not just which library +- Mention versions when they matter +- If the first result isn't right, ask for a different part of the docs + +``` +# Good +How do I handle file uploads with the Supabase Storage API? + +# Less specific +How does Supabase storage work? +``` + + + +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/clients/copilot-cli.mdx b/docs/clients/copilot-cli.mdx new file mode 100644 index 0000000..e58c5bc --- /dev/null +++ b/docs/clients/copilot-cli.mdx @@ -0,0 +1,125 @@ +--- +title: GitHub Copilot CLI +description: Using Context7 with GitHub Copilot CLI +--- + +Context7 integrates with [GitHub Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) to provide current library documentation instead of relying on training data. The Context7 plugin ships the MCP server together with a skill, an agent, and a command, so documentation lookups work out of the box. + +## Installation + +Add the Context7 marketplace and install the plugin: + +```bash +copilot plugin marketplace add upstash/context7 +copilot plugin install context7@context7-marketplace +``` + +You can also run the same steps from an interactive session with `/plugin marketplace add upstash/context7` and `/plugin install context7@context7-marketplace`. + +For manual MCP configuration (for example, to add an API key for higher rate limits), see [All MCP Clients](/resources/all-clients). Create or manage API keys in the [Context7 dashboard](https://context7.com/dashboard). + +--- + +## What's Included + + + +The tools for fetching documentation (`resolve-library-id`, `query-docs`) + + +Auto-triggers documentation lookups when you ask about libraries + + +A `docs-researcher` agent for focused lookups that keep context lean + + +`/context7:docs` for manual documentation queries + + + +--- + +## Using Context7 + +The bundled skill triggers automatically when you ask about libraries — no need to say "use context7". You can also invoke it explicitly: + +``` +use context7 to show me how to set up middleware in Next.js 15 +use context7 for Prisma query examples with relations +use context7 for the Supabase syntax for row-level security +``` + +If you know the library ID, use it directly to skip resolution: + +``` +use context7 with /supabase/supabase for authentication docs +use context7 with /vercel/next.js for app router setup +``` + +### Skills + +The documentation lookup skill recognizes when documentation would help and fetches it automatically. + + + +- Setup questions: "How do I configure Next.js middleware?" +- Code generation: "Write a Prisma query for user relations" +- API references: "What are the Supabase auth methods?" +- Framework mentions: React, Vue, Svelte, Express, Tailwind, etc. + + +1. **Resolve**: Finds the library ID using `resolve-library-id` with your question as context +2. **Select**: Picks the best match based on name accuracy and quality scores +3. **Fetch**: Calls `query-docs` with the library ID and your specific question +4. **Return**: Provides code examples and explanations from current documentation + + + +### Agents + +When you're in the middle of a long task and don't want documentation tool calls cluttering your context, use the `docs-researcher` agent. It runs in a separate context and returns just the answer: + +```bash +copilot --agent docs-researcher -p "how do I set up Prisma with PostgreSQL?" +``` + +| Scenario | Use | +|----------|-----| +| Deep into a task with long context | Agent | +| Want to avoid context bloat | Agent | +| Context is short | Inline tools | +| Want docs visible in conversation | Inline tools | + +### Commands + +`/context7:docs` is a manual command for documentation lookups. + +**Format:** +``` +/context7:docs [query] +``` + +**Examples:** + + + +``` +/context7:docs react hooks +/context7:docs next.js authentication +/context7:docs prisma relations +``` + + +``` +/context7:docs /vercel/next.js app router +/context7:docs /supabase/supabase row level security +``` + +Using a library ID directly skips the resolution step. + + + +**When to use:** +- You know exactly which library and topic you need +- You want a quick lookup without explaining your full context +- You're testing what documentation is available diff --git a/docs/clients/cursor.mdx b/docs/clients/cursor.mdx new file mode 100644 index 0000000..e855fa4 --- /dev/null +++ b/docs/clients/cursor.mdx @@ -0,0 +1,125 @@ +--- +title: Cursor +description: Using Context7 with Cursor +--- + +Context7 brings up-to-date library documentation directly into Cursor. Instead of getting outdated code examples from training data, you get current documentation from source repositories. + +## Installation + +Run the setup command to configure Context7 for Cursor: + +```bash +npx ctx7 setup --cursor +``` + +Authenticates via OAuth, generates an API key, and installs the appropriate skill. You can choose between CLI or MCP mode. + +For manual MCP installation or other configuration options, see [All MCP Clients](/resources/all-clients). + +--- + +## Setting Up Rules + +With `ctx7 setup`, a skill is installed that triggers Context7 automatically. If you prefer to use a rule instead, add one in Cursor. + + + + + +Go to `Cursor` → `Settings...` → `Cursor Settings` → `Rules and Commands`. You can also press `Cmd+Shift+P` (or `Ctrl+Shift+P` on Windows/Linux) and type "Cursor Settings". + + + Cursor Rules and Commands + + + +``` +Always use Context7 MCP when I ask about library documentation, +API references, or need code examples from external packages. +``` + + + + +Create a `.cursorrules` file in your project root: + +``` +# Context7 Integration + +When the user asks about: +- Library APIs or documentation +- Framework setup or configuration +- Code examples for external packages +- How to use a specific library feature + +Automatically use Context7 MCP to fetch current documentation. Don't rely on training data for library-specific code. +``` + +This makes Context7 part of your project's standard workflow and can be version-controlled. + + + + +--- + +## Using Context7 + +Add "use context7" to your prompts to fetch current documentation: + +``` +use context7 to show me how to set up middleware in Next.js 15 +use context7 for Prisma query examples with relations +use context7 for the Supabase syntax for row-level security +``` + +If you know the library ID, use it directly to skip resolution: + +``` +use context7 with /supabase/supabase for authentication docs +use context7 with /vercel/next.js for app router setup +``` + +--- + +## Tips + + + +Use **global config** (`~/.cursor/mcp.json`) when: +- You want Context7 available in all projects +- You're using a personal API key + +Use **project config** (`.cursor/mcp.json`) when: + +- The project has specific Context7 requirements +- You want to share the setup with teammates +- Different projects need different API keys + + + +Context7 works well with Cursor's Composer feature. When you're building something that involves external libraries: + +1. Start with a prompt that mentions the libraries you need +2. Context7 fetches the relevant docs +3. Composer uses those docs to generate accurate code + +This is especially useful for newer library versions that might not be in Cursor's training data. + + + + +- Be specific about what you're trying to do, not just which library +- Mention versions when they matter +- If the first result isn't right, ask for a different part of the docs + +``` +# Good +How do I handle file uploads with the Supabase Storage API? + +# Less specific +How does Supabase storage work? +``` + + + diff --git a/docs/clients/opencode.mdx b/docs/clients/opencode.mdx new file mode 100644 index 0000000..d990776 --- /dev/null +++ b/docs/clients/opencode.mdx @@ -0,0 +1,76 @@ +--- +title: OpenCode +description: Using Context7 with OpenCode +--- + +Context7 integrates with [OpenCode](https://opencode.ai/) to provide current library documentation instead of relying on training data. Get accurate, up-to-date code examples directly in your coding sessions. + + +For more details on MCP server configuration in OpenCode, see the [OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers/). + + +## Installation + +Run the setup command to configure Context7 for OpenCode: + +```bash +npx ctx7 setup --opencode +``` + +Authenticates via OAuth, generates an API key, and installs the appropriate skill. You can choose between CLI or MCP mode. + +For manual MCP installation or other configuration options, see [All MCP Clients](/resources/all-clients). + +--- + +## Using Context7 + +With `ctx7 setup`, a skill is installed that triggers automatically when you ask about libraries. You can also invoke it explicitly: + +``` +use context7 to show me how to set up middleware in Next.js 15 +use context7 for Prisma query examples with relations +use context7 for the Supabase syntax for row-level security +``` + +If you know the library ID, use it directly to skip resolution: + +``` +use context7 with /supabase/supabase for authentication docs +use context7 with /vercel/next.js for app router setup +``` + +You can also add instructions to your `AGENTS.md` file: + +```markdown AGENTS.md +When you need to search docs, use Context7. +``` + +--- + +## Tips + + + +- Be specific about what you're trying to do, not just which library +- Mention versions when they matter +- If the first result isn't right, ask for a different part of the docs + +``` +# Good +How do I handle file uploads with the Supabase Storage API? + +# Less specific +How does Supabase storage work? +``` + + + +You can place your `opencode.json` in your project directory to have project-specific configurations. This is useful when: + +- Different projects need different API keys +- You want to share the config with your team via version control +- A project requires specific Context7 settings + + + diff --git a/docs/clients/pi.mdx b/docs/clients/pi.mdx new file mode 100644 index 0000000..29198cd --- /dev/null +++ b/docs/clients/pi.mdx @@ -0,0 +1,90 @@ +--- +title: Pi +description: Using Context7 with the Pi coding agent +--- + +Context7 integrates with the [Pi coding agent](https://pi.dev) through the official [`@upstash/context7-pi`](https://github.com/upstash/context7/tree/master/packages/pi) extension. Instead of relying on training data, Pi gets current library documentation directly in your coding sessions. + +The extension is self-contained — it registers Context7's tools natively in Pi, so there's no separate MCP server to run. + +## Installation + +Install the extension with Pi's package command: + +```bash +pi install npm:@upstash/context7-pi +``` + +## Authentication + +The extension works out of the box at IP-based rate limits — useful for trying it out. For higher quotas and access to private repositories, generate a free key at the [Context7 dashboard](https://context7.com/dashboard) and export it: + +```bash +export CONTEXT7_API_KEY=ctx7sk_... +``` + +Set it in your shell profile so Pi picks it up on launch. + +--- + +## What it adds + + + +Converts a package or product name to a Context7 library ID (e.g. `Next.js` → `/vercel/next.js`). The agent calls this first. + + +Fetches documentation and code examples for a resolved library ID. + + +Teaches the agent to reach for these tools whenever you ask about a library, framework, SDK, API, CLI tool, or cloud service. + + +Runs the resolve + query flow in one shot for manual lookups. + + + +--- + +## Using Context7 + +Once installed, the skill triggers automatically when you ask about libraries — just ask a docs question and the tools are invoked for you: + +``` +how do I configure caching in Next.js 16? +use the Prisma syntax for relations +what are the Supabase auth methods? +``` + +For a manual lookup, use the slash command: + +``` +/c7-docs +``` + +For example: + +``` +/c7-docs next.js Cache Components +/c7-docs supabase row level security +``` + +--- + +## Tips + + + +- Be specific about what you're trying to do, not just which library +- Mention versions when they matter +- If the first result isn't right, ask for a different part of the docs + +``` +# Good +How do I handle file uploads with the Supabase Storage API? + +# Less specific +How does Supabase storage work? +``` + + diff --git a/docs/clients/vscode.mdx b/docs/clients/vscode.mdx new file mode 100644 index 0000000..387e7d6 --- /dev/null +++ b/docs/clients/vscode.mdx @@ -0,0 +1,76 @@ +--- +title: VS Code +description: Using Context7 with VS Code +--- + +The [Context7 VS Code extension](https://marketplace.visualstudio.com/items?itemName=Upstash.context7-mcp) registers the Context7 MCP server with VS Code's built-in MCP support, so AI features like Copilot Chat in agent mode get current library documentation instead of relying on training data. + +The extension connects to the hosted server at `https://mcp.context7.com/mcp`. There is no local server process to manage and nothing to update manually. The source is available at [upstash/context7-vscode-extension](https://github.com/upstash/context7-vscode-extension). + +## Installation + +Install **Context7 MCP Server** from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Upstash.context7-mcp), or search for `Upstash.context7-mcp` in the Extensions view. + +Requires VS Code 1.101 or later. + +The server registers automatically when the extension activates. To confirm, run the **MCP: List Servers** command and check that "Context7" is listed. + +If you prefer to configure the MCP server yourself instead of using the extension, see [All MCP Clients](/resources/all-clients). + +--- + +## Adding an API Key + +An API key gives you higher rate limits and access to private repositories. Create one in the [Context7 dashboard](https://context7.com/dashboard). + + + +Press `Cmd+,` (or `Ctrl+,` on Windows/Linux) and search for "context7". + + +Paste your key into the **Context7: Api Key** field, or add it to `settings.json` directly: + +```json +{ + "context7.apiKey": "YOUR_API_KEY" +} +``` + + +Changing the key stops the running server so the new key can be picked up. Restart it via **MCP: List Servers** → **Context7** → **Start Server**, or just send a new chat request, which prompts to start it. No window reload required. + + + + +Keep the API key in your user settings rather than workspace settings if you commit `.vscode/settings.json` to version control. + + +--- + +## Using Context7 + +Add "use context7" to your prompts in Copilot Chat: + +``` +use context7 to show me how to set up middleware in Next.js 15 +use context7 for Prisma query examples with relations +use context7 for the Supabase syntax for row-level security +``` + +If you know the library ID, use it directly to skip resolution: + +``` +use context7 with /supabase/supabase for authentication docs +use context7 with /vercel/next.js for app router setup +``` + + +Add a rule to your AI assistant's instructions (e.g. `.github/copilot-instructions.md`) telling it to use Context7 for code generation and library questions, so you don't have to type "use context7" every time. + + +### Available Tools + +The extension exposes the two Context7 tools to VS Code: + +1. **`resolve-library-id`**: Resolves a package or product name to a Context7-compatible library ID +2. **`query-docs`**: Fetches up-to-date documentation for a library diff --git a/docs/contact.mdx b/docs/contact.mdx new file mode 100644 index 0000000..e9588ff --- /dev/null +++ b/docs/contact.mdx @@ -0,0 +1,4 @@ +--- +title: Contact +url: https://context7.com/contact +--- diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 0000000..4656619 --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,297 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "Context7 MCP", + "description": "Up-to-date code docs for any prompt.", + "redirects": [ + { + "source": "/enterprise/azure-apim", + "destination": "/enterprise/enterprise-managed-auth/entra" + } + ], + "colors": { + "primary": "#10B981", + "light": "#ECFDF5", + "dark": "#064E3B" + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude" + ] + }, + "navigation": { + "groups": [ + { + "group": "Overview", + "pages": [ + "overview", + "installation", + "plans-pricing", + "clients/cli", + "adding-libraries", + "library-owners", + "library-updates", + "api-guide", + "tips" + ] + }, + { + "group": "How To", + "pages": [ + { + "group": "Authentication", + "pages": [ + "howto/api-keys", + "howto/oauth" + ] + }, + "howto/claiming-libraries", + "howto/chat-widget", + "howto/verification", + "howto/private-sources", + "howto/policies", + "howto/rules", + "howto/usage", + "howto/teamspace" + ] + }, + { + "group": "Enterprise", + "pages": [ + "enterprise", + { + "group": "Enterprise-Managed Auth", + "pages": [ + "enterprise/enterprise-managed-auth/entra", + "enterprise/enterprise-managed-auth/okta" + ] + }, + { + "group": "On-Premise", + "pages": [ + "enterprise/on-premise", + { + "group": "Integrations", + "pages": [ + "enterprise/integrations/github", + "enterprise/integrations/confluence" + ] + }, + { + "group": "Security", + "pages": [ + "enterprise/security/entra-sso", + "enterprise/security/oidc-sso" + ] + }, + { + "group": "Deployment", + "pages": [ + "enterprise/deployment/docker", + "enterprise/deployment/kubernetes" + ] + }, + { + "group": "Features", + "pages": [ + "enterprise/library-import", + "enterprise/gitops", + "enterprise/backup-restore" + ] + }, + { + "group": "API Reference", + "pages": [ + "enterprise/api/authentication", + { + "group": "Search", + "pages": ["enterprise/api/search/search-for-libraries"] + }, + { + "group": "Context", + "pages": ["enterprise/api/context/get-documentation-context"] + }, + { + "group": "Parse", + "pages": [ + "enterprise/api/parse/parse-a-git-repository", + "enterprise/api/parse/parse-an-openapi-spec-by-url", + "enterprise/api/parse/upload-an-openapi-spec-file", + "enterprise/api/parse/import-libraries", + "enterprise/api/parse/parse-a-website", + "enterprise/api/parse/refresh-a-library", + "enterprise/api/parse/get-parse-status" + ] + } + ] + } + ] + } + ] + }, + { + "group": "Security", + "pages": [ + "security/overview", + "security/data-privacy", + "security/infrastructure", + "security/auth-and-access-control", + "security/compliance-and-reporting", + "security/data-safety", + "security/best-practices" + ] + }, + { + "group": "Clients", + "pages": [ + "clients/claude-code", + "clients/codex", + "clients/copilot-cli", + "clients/cursor", + "clients/opencode", + "clients/pi", + "clients/vscode", + "resources/all-clients" + ] + }, + { + "group": "SDKs", + "pages": [ + { + "group": "TypeScript", + "pages": [ + "sdks/ts/getting-started", + { + "group": "Commands", + "pages": [ + "sdks/ts/commands/search-library", + "sdks/ts/commands/get-context" + ] + } + ] + } + ] + }, + { + "group": "Agentic Tools", + "pages": [ + "agentic-tools/overview", + { + "group": "Vercel AI SDK", + "pages": [ + "agentic-tools/ai-sdk/getting-started", + { + "group": "Tools", + "pages": [ + "agentic-tools/ai-sdk/tools/resolve-library-id", + "agentic-tools/ai-sdk/tools/query-docs" + ] + }, + { + "group": "Agents", + "pages": [ + "agentic-tools/ai-sdk/agents/context7-agent" + ] + } + ] + } + ] + }, + { + "group": "API Reference", + "openapi": "openapi.json" + }, + { + "group": "Integrations", + "pages": [ + "integrations/github-actions", + "integrations/code-rabbit", + "integrations/factory-ai", + "integrations/tembo", + "integrations/mastra" + ] + }, + { + "group": "Resources", + "pages": [ + "resources/developer", + "resources/troubleshooting" + ] + } + ] + }, + "api": { + "playground": { + "display": "simple" + } + }, + "logo": { + "light": "/public/logo/logo.svg", + "dark": "/public/logo/logo-dark.svg", + "href": "https://context7.com" + }, + "favicon": "/public/favicon.ico", + "navbar": { + "links": [ + { + "label": "Contact", + "href": "https://context7.com/contact" + }, + { + "label": "GitHub", + "href": "https://github.com/upstash/context7" + } + ], + "primary": { + "type": "button", + "label": "Dashboard", + "href": "https://context7.com" + } + }, + "footer": { + "socials": { + "x": "https://x.com/context7ai", + "github": "https://github.com/upstash/context7", + "discord": "https://upstash.com/discord" + }, + "links": [ + { + "header": "Resources", + "items": [ + { + "label": "Website", + "href": "https://context7.com" + }, + { + "label": "Submit a Library", + "href": "https://context7.com/add-library" + }, + { + "label": "Dashboard", + "href": "https://context7.com/dashboard" + } + ] + }, + { + "header": "Community", + "items": [ + { + "label": "GitHub", + "href": "https://github.com/upstash/context7" + }, + { + "label": "Discord", + "href": "https://upstash.com/discord" + }, + { + "label": "Twitter", + "href": "https://x.com/context7ai" + } + ] + } + ] + } +} diff --git a/docs/enterprise.mdx b/docs/enterprise.mdx new file mode 100644 index 0000000..5ebde6f --- /dev/null +++ b/docs/enterprise.mdx @@ -0,0 +1,96 @@ +--- +title: Enterprise +sidebarTitle: Overview +description: Turn your internal documentation into LLM-ready context for developers, coding agents, and engineering leaders +--- + +Context7 Enterprise converts your internal documentation into structured, high-quality context optimized for LLMs — enabling human developers, coding agents, and engineering leaders to build faster and operate with clarity. + +## Core Use Cases + +### Assist Human Developers + +Cut onboarding time and reduce internal support load. + +- Faster onboarding and fewer interruptions +- Immediate API/service reference inside IDEs +- Always-up-to-date documentation context +- Reduced Slack/Teams dependency + +### Power Coding Agents With Correct Documentation + +Let your agents write correct code on the first try. + +- Supply agents with accurate repo + docs context +- Reduce hallucinations and incorrect API calls +- Enable autonomous generation, refactoring, and analysis +- Feed structured context into LangGraph/agent frameworks + +### Engineering Management & Knowledge Governance + +One source of truth. Zero stale docs. + +- Enforce documentation and context rules across projects +- Automatically parse APIs, RST/Sphinx, MDX, OpenAPI +- Detect outdated or inconsistent sections +- Maintain a single source of truth across engineering + +## Enterprise Features + +- **SOC 2 certified** cloud infrastructure +- **SSO** (SAML, OAuth, OIDC) +- Unlimited seats and teamspaces +- Custom volume expansions and high-usage plans +- Private GitHub / GitLab / Bitbucket repository ingestion +- Professional support with response time SLA +- On-premise deployment options available + +## Security & Compliance + +Context7 runs on **SOC 2 Type II** compliant infrastructure provided by [Upstash](https://upstash.com). Key security highlights include: + +- **Privacy-first architecture** — your original prompts and code never leave your AI assistant. Only MCP-formulated search queries reach the Context7 API, and sensitive data is stripped before transmission. +- **Encryption** at rest and in transit (TLS 1.2+) +- **VPC isolation**, RBAC, DDoS protection, and 24/7 monitoring +- **API key security** — cryptographically generated, hashed, encrypted, and rate-limited +- **Enterprise SSO** — supports SAML 2.0, OAuth 2.0, and OpenID Connect (OIDC) +- **GDPR compliant** with data access, deletion, and portability rights +- Data stored in the US and EU with cross-border transfers following GDPR and EU-U.S. Data Privacy Framework +- **ISO 27001** certification in progress +- Open-source MCP server — publicly auditable at [github.com/upstash/context7](https://github.com/upstash/context7) + +Enterprise customers can also disable query storage, use their own LLM provider for code extraction and private library ranking, and limit context retrieval to privately indexed documentation only. + +For full details, see the [Security](/security/overview) page and the [Upstash Trust Center](https://trust.upstash.com/). + +## Quality & Safety + +Context7 is built with retrieval quality and trust at its core: + +- **Benchmark-driven retrieval** — a library benchmark system generates developer-style questions and measures how effectively each library answers them. Scores are publicly visible and help prioritize better-performing libraries during retrieval. +- **Trust scores** — every library receives a trust score based on repository signals (stars, activity, account age) and website signals (TLS, domain authority, backlinks). This ensures reliable, well-established libraries are surfaced first. +- **Deduplication** — exact match checking and cosine similarity filtering remove redundant code snippets and overlapping documentation content. +- **Version-aware parsing** — a version analyzer detects multi-version documentation structures, ensuring only current docs are stored by default while older versions remain accessible. +- **Prompt injection protection** — a two-pass detection pipeline combining complementary stages blocks malicious documentation content while minimizing false positives. Pipelines are regularly updated to address evolving attack methods. +- **Minimal data ingestion** — Context7 does not ingest user code, conversation history, or other sensitive data. + +For more details, see the [Quality and Safety in Context7](https://upstash.com/blog/context7-quality-and-safety) blog post. + +## Pricing + +For pricing details and custom plans, [contact us](mailto:context7@upstash.com). + +## About Upstash + +Context7 is built by [Upstash](https://upstash.com), a serverless data platform powering 80,000+ active databases worldwide. Upstash delivers managed Redis, Vector, Queue, and Search services — processing 850+ billion requests per month with 99.99%+ uptime. Backed by Andreessen Horowitz (a16z) and headquartered in California, Upstash brings deep distributed systems expertise. Context7 follows the same engineering, reliability, and security standards. + +## Contact + + + + context7@upstash.com + + + context7.com + + diff --git a/docs/enterprise/api/authentication.mdx b/docs/enterprise/api/authentication.mdx new file mode 100644 index 0000000..4a5c873 --- /dev/null +++ b/docs/enterprise/api/authentication.mdx @@ -0,0 +1,64 @@ +--- +title: "Authentication" +description: "How to authenticate requests to your on-premise Context7 instance" +--- + +The on-premise API supports API keys for server-to-server and MCP access. Pass the key in the `Authorization` header: + +```bash +Authorization: Bearer ctx7op-xxxxxxxx_xxxxxxxxxxxxxxxx +``` + +Keys are scoped to the user account that created them and inherit that user's role (`admin` or `member`). There are no per-key scopes or expiry - revoke a key to invalidate it. + +## Creating an API Key + + + + Go to **Personal Settings > API Keys** in the admin dashboard and click **Create API Key**. + + + ![API Keys settings page](/images/enterprise/api-keys/api-keys-empty.png) + + + + Give the key a descriptive name so you know which client or service is using it (e.g. `CI pipeline`, `Cursor`). + + + ![Create API Key dialog](/images/enterprise/api-keys/api-keys-create-dialog.png) + + + + Copy the full key value before closing the dialog. It is only shown once. + + + ![API Key Created dialog showing the key value](/images/enterprise/api-keys/api-keys-created.png) + + + + +API keys are shown only once at creation. Store yours securely before closing the dialog. + +## Revoking a Key + +Go to **Settings > API Keys** and click the delete icon next to the key. Revocation is immediate and cannot be undone. Update any integrations using the key before revoking. + +## Roles + +| Role | Access | +|---|---| +| `admin` | Full access to all endpoints including settings, user management, and delete operations | +| `member` | Can trigger parsing and search. Cannot access admin endpoints | + +Default credentials on a fresh install are `admin` / `admin`. Change them immediately from **Settings > Change Credentials**. + +## Anonymous Access + +Certain operations can be allowed without authentication. Configure them from **Settings > Permissions**: + +| Permission | Default | +|---|---| +| Anonymous parse / refresh | Off | +| Anonymous delete | Off | + +The search (`GET /v2/libs/search`) and context (`GET /v2/context`) endpoints are always publicly accessible unless a global `API_KEY` environment variable is set, in which case every endpoint requires a bearer token. diff --git a/docs/enterprise/api/context/get-documentation-context.mdx b/docs/enterprise/api/context/get-documentation-context.mdx new file mode 100644 index 0000000..dd5c56a --- /dev/null +++ b/docs/enterprise/api/context/get-documentation-context.mdx @@ -0,0 +1,5 @@ +--- +title: "Get documentation context" +description: "Retrieve documentation snippets for a library ranked by relevance to your query" +openapi: "openapi-enterprise.json GET /v2/context" +--- diff --git a/docs/enterprise/api/parse/get-parse-status.mdx b/docs/enterprise/api/parse/get-parse-status.mdx new file mode 100644 index 0000000..f77affd --- /dev/null +++ b/docs/enterprise/api/parse/get-parse-status.mdx @@ -0,0 +1,5 @@ +--- +title: "Get parse status" +description: "Returns the status of all active and queued parse jobs" +openapi: "openapi-enterprise.json GET /parse-status" +--- diff --git a/docs/enterprise/api/parse/import-libraries.mdx b/docs/enterprise/api/parse/import-libraries.mdx new file mode 100644 index 0000000..c51bbe9 --- /dev/null +++ b/docs/enterprise/api/parse/import-libraries.mdx @@ -0,0 +1,5 @@ +--- +title: "Import a library bundle" +description: "Import pre-parsed libraries into an airgapped on-premise install, as a JSON body or a Context7 Cloud export file" +openapi: "openapi-enterprise.json POST /import-libraries" +--- diff --git a/docs/enterprise/api/parse/parse-a-git-repository.mdx b/docs/enterprise/api/parse/parse-a-git-repository.mdx new file mode 100644 index 0000000..962258f --- /dev/null +++ b/docs/enterprise/api/parse/parse-a-git-repository.mdx @@ -0,0 +1,5 @@ +--- +title: "Parse a Git repository" +description: "Queue a GitHub or GitLab repository for parsing and indexing" +openapi: "openapi-enterprise.json POST /parse" +--- diff --git a/docs/enterprise/api/parse/parse-a-website.mdx b/docs/enterprise/api/parse/parse-a-website.mdx new file mode 100644 index 0000000..200f9f3 --- /dev/null +++ b/docs/enterprise/api/parse/parse-a-website.mdx @@ -0,0 +1,5 @@ +--- +title: "Parse a website" +description: "Crawl and index a public website starting from the given URL" +openapi: "openapi-enterprise.json POST /parse-website" +--- diff --git a/docs/enterprise/api/parse/parse-an-openapi-spec-by-url.mdx b/docs/enterprise/api/parse/parse-an-openapi-spec-by-url.mdx new file mode 100644 index 0000000..1eb0a3f --- /dev/null +++ b/docs/enterprise/api/parse/parse-an-openapi-spec-by-url.mdx @@ -0,0 +1,5 @@ +--- +title: "Parse an OpenAPI spec by URL" +description: "Queue a remote OpenAPI specification (JSON or YAML) for parsing and indexing" +openapi: "openapi-enterprise.json POST /parse-openapi" +--- diff --git a/docs/enterprise/api/parse/refresh-a-library.mdx b/docs/enterprise/api/parse/refresh-a-library.mdx new file mode 100644 index 0000000..ac79d2f --- /dev/null +++ b/docs/enterprise/api/parse/refresh-a-library.mdx @@ -0,0 +1,5 @@ +--- +title: "Refresh a library" +description: "Re-parse an existing library using its stored settings" +openapi: "openapi-enterprise.json POST /projects/{projectId}/refresh" +--- diff --git a/docs/enterprise/api/parse/upload-an-openapi-spec-file.mdx b/docs/enterprise/api/parse/upload-an-openapi-spec-file.mdx new file mode 100644 index 0000000..a4c7efe --- /dev/null +++ b/docs/enterprise/api/parse/upload-an-openapi-spec-file.mdx @@ -0,0 +1,5 @@ +--- +title: "Upload an OpenAPI spec file" +description: "Upload an OpenAPI specification file directly for parsing and indexing" +openapi: "openapi-enterprise.json POST /parse-openapi-upload" +--- diff --git a/docs/enterprise/api/search/search-for-libraries.mdx b/docs/enterprise/api/search/search-for-libraries.mdx new file mode 100644 index 0000000..daffa00 --- /dev/null +++ b/docs/enterprise/api/search/search-for-libraries.mdx @@ -0,0 +1,5 @@ +--- +title: "Search for libraries" +description: "Search locally indexed libraries by name" +openapi: "openapi-enterprise.json GET /v2/libs/search" +--- diff --git a/docs/enterprise/backup-restore.mdx b/docs/enterprise/backup-restore.mdx new file mode 100644 index 0000000..883fbd9 --- /dev/null +++ b/docs/enterprise/backup-restore.mdx @@ -0,0 +1,151 @@ +--- +title: "Backup and Restore" +sidebarTitle: "Backup & Restore" +--- + +Context7 On-Premise can back up all of its data into a single archive, on a schedule or on demand. A backup contains everything needed to rebuild your deployment on a fresh machine: the SQLite database (configuration, credentials, indexed libraries), the vector index, and the encryption key that protects stored secrets. + +Backups run safely while the server is serving traffic. The database snapshot uses SQLite's online backup API, so you don't need a maintenance window. + + +Backup archives include the database and the encryption key, which means anyone holding an archive can read your stored credentials (LLM API keys, Git tokens). Store backups with the same care as the data volume itself. For S3, use a private bucket with server-side encryption. + + +## Configuring Backups + +Open **Settings → Backup** in the dashboard. Choose a destination, set a schedule, and save. + +### Local or Network Path + +Writes archives to a directory on the server's filesystem. Use this for air-gapped deployments or when you back up to an NFS mount. + +When running in Docker, mount a dedicated volume for backups so they survive independently of the data volume: + +```yaml +services: + context7: + # ... + volumes: + - context7-data:/data + - context7-backups:/backups + +volumes: + context7-data: + context7-backups: +``` + +Then set the backup directory to `/backups` in the dashboard. + +### S3 + +Works with AWS S3 and any S3-compatible store such as MinIO or Ceph. + +| Field | Description | +| ----- | ----------- | +| Bucket | Bucket name (required) | +| Region | Bucket region, defaults to `us-east-1` | +| Access Key ID / Secret | Static credentials. Leave blank to use the AWS default credential chain (IAM role, environment variables) | +| Endpoint | Custom endpoint for S3-compatible storage. Leave blank for AWS | +| Path-style addressing | Enable for most MinIO setups | +| Key prefix | Optional prefix inside the bucket, e.g. `context7/` | + +The secret key is stored encrypted in the local database. + +### Schedule and Retention + +Pick a preset (daily, every 6 hours, weekly) or enter a custom cron expression. Retention keeps the newest N archives and prunes older ones automatically; choose **Keep all** to retain everything. + +If an indexing job is running when a scheduled backup fires, the backup still completes, but that one library may be only partially indexed. Schedule backups for quiet hours, or simply re-index that library after a restore. + +## Running a Backup Manually + +Click **Back up now** in the dashboard, or call the API: + +```bash +curl -X POST http://localhost:3000/api/backup \ + -H "Cookie: " +``` + +All backup endpoints require an admin session and keep working even if your license has expired, so you can always get your data out. + +| Endpoint | Description | +| -------- | ----------- | +| `POST /api/backup` | Start a backup in the background | +| `GET /api/backup/status` | Whether a backup is running, plus the last result | +| `GET /api/backups` | List available archives | +| `GET /api/backups//download` | Download an archive (local destination only) | +| `GET /api/backup/config` / `PUT` | Read or update the backup configuration | + +## Restoring + +Restore a backup from the dashboard (for local backups) or with the offline CLI (for S3 backups, scripted recovery, or a fresh machine). + +In every case the restore never deletes your current data. It moves the existing database, vector index, and encryption key into a `pre-restore-` directory inside the data volume, so you can roll back. Delete that directory once you've verified the restore. + + +A backup created by a newer Context7 version cannot be restored into an older installation; the restore tool will refuse and tell you to upgrade first. Backups from older versions restore fine, and the database is migrated automatically the next time the server starts. + + +### From the dashboard + +Open **Settings → Backup**, find the backup in the list, and click the restore icon. Context7 validates the archive, shows what it contains (created date, libraries, schema version), and asks you to confirm. It then stages the restore and restarts to apply it, because the live database and vector index cannot be swapped while the server is running. Under Docker or Kubernetes the server comes back automatically; otherwise start it again after it stops. + +### Offline with the CLI + +Run the CLI with the server stopped. For S3 backups, download the archive to the machine first. + +#### Docker + +```bash +# 1. Stop the server +docker compose stop context7 + +# 2. Run the restore against the same volumes +docker compose run --rm --no-deps context7 \ + node dist/enterprise/restore.mjs /backups/context7-backup-2026-06-12T02-00-00.tar.gz --yes + +# 3. Start the server again +docker compose start context7 +``` + +If the archive is not already inside a mounted volume (for example, you downloaded it from S3), copy it in first: + +```bash +docker compose cp ./context7-backup-2026-06-12T02-00-00.tar.gz context7:/data/ +``` + +#### Kubernetes + +Scale the StatefulSet down, run the restore in a one-off pod that mounts the same PVC, then scale back up: + +```bash +kubectl -n context7 scale statefulset context7 --replicas=0 + +kubectl -n context7 run context7-restore --rm -it --restart=Never \ + --image=ghcr.io/context7/enterprise:latest \ + --overrides='{"spec":{"imagePullSecrets":[{"name":"context7-registry"}],"containers":[{"name":"context7-restore","image":"ghcr.io/context7/enterprise:latest","command":["node","dist/enterprise/restore.mjs","/data/context7-backup-2026-06-12T02-00-00.tar.gz","--yes"],"volumeMounts":[{"name":"data","mountPath":"/data"}]}],"volumes":[{"name":"data","persistentVolumeClaim":{"claimName":"data-context7-0"}}]}}' + +kubectl -n context7 scale statefulset context7 --replicas=1 +``` + +Use `kubectl cp` to place the archive on the volume first if it isn't there already. + +#### Running locally + +If you run Context7 without Docker: + +```bash +npm run ctx7:restore -- /path/to/context7-backup-2026-06-12T02-00-00.tar.gz +``` + +The command prompts for confirmation before replacing anything. Pass `--yes` to skip the prompt in scripts. + +## Disaster Recovery Checklist + +1. Deploy a fresh Context7 instance on the new machine (same or newer version). +2. Don't run the setup wizard. Stop the server instead. +3. Copy your latest backup archive onto the machine. +4. Run the restore as shown above. +5. Start the server. Your configuration, credentials, users, indexed libraries, and search index are all back. + +Because the encryption key travels inside the archive, restored credentials work immediately on the new machine. Nothing needs to be re-entered. diff --git a/docs/enterprise/deployment/docker.mdx b/docs/enterprise/deployment/docker.mdx new file mode 100644 index 0000000..376dcc5 --- /dev/null +++ b/docs/enterprise/deployment/docker.mdx @@ -0,0 +1,131 @@ +--- +title: "Docker Deployment" +sidebarTitle: "Docker" +description: "Deploy Context7 On-Premise with Docker Compose" +--- + +Deploy Context7 On-Premise with Docker Compose. This guide assumes you have completed the [On-Premise setup](/enterprise/on-premise) and have a valid license key. + +## Prerequisites + +- Docker and Docker Compose installed +- Context7 license key + +## Registry Authentication + +Context7 Enterprise images are hosted on `ghcr.io` and require authentication. Log in using your license key: + +```bash +LICENSE_KEY="" + +TOKEN=$(curl -s -H "Authorization: Bearer $LICENSE_KEY" \ + https://context7.com/api/v1/license/registry-token | jq -r '.token') + +docker login ghcr.io -u x-access-token -p $TOKEN +``` + +Docker stores these credentials locally. `docker compose` will use them automatically when pulling the image. You can also pull manually: + +```bash +docker pull ghcr.io/context7/enterprise:latest +``` + +## Docker Compose + +Create a `docker-compose.yml`: + +```yaml +services: + context7: + image: ghcr.io/context7/enterprise:latest + container_name: context7 + restart: unless-stopped + ports: + - "3000:3000" + volumes: + - context7-data:/data + environment: + - LICENSE_KEY=${LICENSE_KEY} + +volumes: + context7-data: + driver: local +``` + + +The `context7-data` volume is critical. It stores your SQLite database (configuration, credentials, indexed libraries) and all vector embeddings. Without a persistent volume, all data is lost when the container restarts or is recreated. Never run without a volume mount in production. + + +Create a `.env` file in the same directory: + +```bash +LICENSE_KEY=ctx7sk-... +``` + +Start the service: + +```bash +docker compose up -d +``` + +Once the container is running, open `http://localhost:3000` in your browser to complete the setup wizard. + +## Operations + +### Updating + +If your registry login has expired, re-authenticate first: + +```bash +LICENSE_KEY="" + +TOKEN=$(curl -s -H "Authorization: Bearer $LICENSE_KEY" \ + https://context7.com/api/v1/license/registry-token | jq -r '.token') + +docker login ghcr.io -u x-access-token -p $TOKEN +``` + +Then pull the latest image and restart the container: + +```bash +docker compose pull +docker compose up -d +``` + +Data persists in the named Docker volume across updates. + +### Health Check + +```bash +curl http://localhost:3000/api/health +``` + +Example response: + +```json +{ + "status": "healthy", + "version": "1.0.0", + "setup": "complete", + "license": "configured", + "licenseInfo": { + "valid": true, + "teamSize": 10, + "expiresAt": "2026-06-01T00:00:00.000Z" + }, + "repos_parsed": 5, + "uptime": 3600, + "connectivity": { + "llm": "configured", + "llm_provider": "openai", + "embedding": "configured", + "embedding_provider": "openai", + "github": "configured", + "gitlab": "not configured" + } +} +``` + +## Connecting AI Clients + +Once deployed, point your MCP clients to your deployment URL. See [Connecting Your AI Client](/enterprise/on-premise#connecting-your-ai-client) for client-specific instructions. diff --git a/docs/enterprise/deployment/kubernetes.mdx b/docs/enterprise/deployment/kubernetes.mdx new file mode 100644 index 0000000..4643dc7 --- /dev/null +++ b/docs/enterprise/deployment/kubernetes.mdx @@ -0,0 +1,341 @@ +--- +title: "Kubernetes Deployment" +sidebarTitle: "Kubernetes" +description: "Deploy Context7 On-Premise on Kubernetes using raw manifests" +--- + +Deploy Context7 On-Premise on Kubernetes using raw manifests. This guide assumes you have completed the [On-Premise setup](/enterprise/on-premise) and have a valid license key. + +## Prerequisites + +- Kubernetes cluster (v1.24+) +- `kubectl` configured for your cluster +- A StorageClass that supports `ReadWriteOnce` volumes +- Context7 license key + +## Registry Authentication + +Context7 Enterprise images are hosted on `ghcr.io` and require authentication. Create an image pull secret using your license key: + +```bash +LICENSE_KEY="" + +# Get a registry token from Context7 +TOKEN=$(curl -s -H "Authorization: Bearer $LICENSE_KEY" \ + https://context7.com/api/v1/license/registry-token | jq -r '.token') + +# Create the namespace and secrets +kubectl create namespace context7 + +kubectl create secret docker-registry context7-registry \ + --namespace context7 \ + --docker-server=ghcr.io \ + --docker-username=x-access-token \ + --docker-password="$TOKEN" \ + --dry-run=client -o yaml | kubectl apply -f - + +kubectl create secret generic context7-config \ + --namespace context7 \ + --from-literal=LICENSE_KEY="$LICENSE_KEY" \ + --dry-run=client -o yaml | kubectl apply -f - +``` + +## Manifests + +Context7 Enterprise runs as a single-replica StatefulSet with persistent storage. The manifests below define the core resources: a StatefulSet for the application, a Service for internal routing, and an Ingress for external access. + +### StatefulSet + +Context7 uses SQLite and LanceDB for local storage, which require a persistent volume. This means it must run as a **StatefulSet with a single replica** since SQLite does not support concurrent writers. + +```yaml statefulset.yaml +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: context7 + namespace: context7 +spec: + serviceName: context7 + replicas: 1 + selector: + matchLabels: + app: context7 + template: + metadata: + labels: + app: context7 + spec: + imagePullSecrets: + - name: context7-registry + terminationGracePeriodSeconds: 60 + containers: + - name: context7 + image: ghcr.io/context7/enterprise:latest + imagePullPolicy: Always + ports: + - containerPort: 3000 + name: http + env: + - name: LICENSE_KEY + valueFrom: + secretKeyRef: + name: context7-config + key: LICENSE_KEY + volumeMounts: + - name: data + mountPath: /data + resources: + requests: + cpu: "1" + memory: "2Gi" + limits: + cpu: "4" + memory: "8Gi" + startupProbe: + httpGet: + path: /api/health + port: http + initialDelaySeconds: 5 + periodSeconds: 5 + failureThreshold: 12 + livenessProbe: + httpGet: + path: /api/health + port: http + periodSeconds: 30 + timeoutSeconds: 5 + failureThreshold: 3 + readinessProbe: + httpGet: + path: /api/health + port: http + periodSeconds: 10 + timeoutSeconds: 5 + failureThreshold: 3 + volumeClaimTemplates: + - metadata: + name: data + spec: + # storageClassName: gp3 # Set this if your cluster has no default StorageClass + accessModes: ["ReadWriteOnce"] + resources: + requests: + storage: 10Gi +``` + + + **Storage class:** If your cluster does not have a default StorageClass, the PVC will stay in `Pending` and the pod won't start. Uncomment `storageClassName` and set it to a StorageClass available in your cluster (e.g. `gp3` on AWS EKS, `standard` on GKE, `default` on AKS). Run `kubectl get sc` to see available options. + + + + **Resource sizing:** The defaults above (1 CPU / 2 GiB request) work for light usage. If you are parsing many large repositories concurrently, increase the limits. Parsing is CPU and memory intensive due to LLM calls and vector indexing. + + + + Do not set `replicas` higher than 1. Context7 uses SQLite which only supports a single writer. Running multiple replicas will cause database lock errors. + + +### Service + +```yaml service.yaml +apiVersion: v1 +kind: Service +metadata: + name: context7 + namespace: context7 +spec: + selector: + app: context7 + ports: + - port: 3000 + targetPort: http + protocol: TCP + name: http + type: ClusterIP +``` + +### Ingress + +```yaml ingress.yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: context7 + namespace: context7 + annotations: + nginx.ingress.kubernetes.io/proxy-body-size: "50m" +spec: + ingressClassName: nginx + tls: + - hosts: + - context7.internal.yourcompany.com + secretName: context7-tls + rules: + - host: context7.internal.yourcompany.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: context7 + port: + number: 3000 +``` + +Replace `context7.internal.yourcompany.com` with your actual hostname and `context7-tls` with your TLS secret. + +## Apply Everything + +After creating the namespace and secrets in the [Registry Authentication](#registry-authentication) step, apply the manifests: + +```bash +kubectl apply -f statefulset.yaml +kubectl apply -f service.yaml +kubectl apply -f ingress.yaml +``` + +Verify the pod is running: + +```bash +kubectl get pods -n context7 +kubectl logs -n context7 context7-0 +``` + +Once the pod is ready, open your Ingress hostname in a browser to complete the setup wizard. + +## Networking Requirements + +Context7 requires outbound connectivity to the following: + +| Destination | Purpose | +|---|---| +| `ghcr.io` | Container image pulls (`imagePullPolicy: Always`) | +| `context7.com` | License validation | +| Your LLM provider (e.g. `api.openai.com`) | AI inference and embeddings | +| `github.com` / `gitlab.com` | Repository cloning | + +If you use NetworkPolicies, ensure egress to these endpoints is allowed: + +```yaml networkpolicy.yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: context7-egress + namespace: context7 +spec: + podSelector: + matchLabels: + app: context7 + policyTypes: + - Egress + egress: + - {} # Allow all egress (simplest) +``` + +For stricter policies, allow egress on port 443 to the specific domains listed above, and ensure egress to `kube-dns` on port 53 (UDP/TCP) is permitted for DNS resolution. + +## Operations + +### Updating + +Pull the latest image and restart: + +```bash +kubectl rollout restart statefulset/context7 -n context7 +``` + +To pin a specific version: + +```bash +kubectl set image statefulset/context7 \ + context7=ghcr.io/context7/enterprise:1.2.0 \ + -n context7 +``` + +If your registry token has expired, refresh it before restarting: + +```bash +LICENSE_KEY="" + +TOKEN=$(curl -s -H "Authorization: Bearer $LICENSE_KEY" \ + https://context7.com/api/v1/license/registry-token | jq -r '.token') + +kubectl create secret docker-registry context7-registry \ + --namespace context7 \ + --docker-server=ghcr.io \ + --docker-username=x-access-token \ + --docker-password="$TOKEN" \ + --dry-run=client -o yaml | kubectl apply -f - +``` + +### Health Monitoring + +The `/api/health` endpoint returns structured JSON with license status, connectivity, and parsed repo count. Point your monitoring stack at it: + +```bash +kubectl exec -n context7 context7-0 -- \ + wget -qO- http://localhost:3000/api/health +``` + +Example response: + +```json +{ + "status": "healthy", + "version": "1.0.0", + "setup": "complete", + "license": "configured", + "licenseInfo": { + "valid": true, + "teamSize": 10, + "expiresAt": "2026-06-01T00:00:00.000Z" + }, + "repos_parsed": 5, + "uptime": 3600, + "connectivity": { + "llm": "configured", + "llm_provider": "openai", + "embedding": "configured", + "embedding_provider": "openai", + "github": "configured", + "gitlab": "not configured" + } +} +``` + +### Logs + +```bash +# Follow logs +kubectl logs -f -n context7 context7-0 + +# Check license and startup status +kubectl logs -n context7 context7-0 | head -20 +``` + +## Troubleshooting + +### Pod is in CrashLoopBackOff + +Context7 validates your license key on startup. If the key is missing, invalid, or expired, the server exits immediately before the health endpoint is available. This means Kubernetes will report `CrashLoopBackOff` rather than a failed probe. + +Check the logs first: + +```bash +kubectl logs -n context7 context7-0 +``` + +Look for `[license]` messages in the first few lines. Common causes: + +- **Missing or incorrect `LICENSE_KEY`** in the `context7-config` secret +- **No outbound connectivity** to `context7.com` for license validation +- **Expired license**: contact [context7@upstash.com](mailto:context7@upstash.com) to renew + + + The startup probe only comes into play after the license is validated. If the pod is crash-looping, the issue is always upstream of the probe. Check logs, not probe events. + + +## Connecting AI Clients + +Once deployed, point your MCP clients to your Ingress URL. See [Connecting Your AI Client](/enterprise/on-premise#connecting-your-ai-client) for client-specific instructions. Replace `localhost:3000` with your Kubernetes Ingress hostname. diff --git a/docs/enterprise/enterprise-managed-auth/entra.mdx b/docs/enterprise/enterprise-managed-auth/entra.mdx new file mode 100644 index 0000000..3680ac4 --- /dev/null +++ b/docs/enterprise/enterprise-managed-auth/entra.mdx @@ -0,0 +1,751 @@ +--- +title: "Azure API Management as MCP gateway" +sidebarTitle: "Microsoft Entra ID" +description: "Route Context7 MCP traffic through Azure API Management with per-user Microsoft Entra ID authentication." +--- + +This guide walks through deploying Azure API Management (APIM) as a gateway in front of `mcp.context7.com`, with per-user authentication backed by your Microsoft Entra tenant. Developers sign in once with their corporate Entra account in their MCP client (for example VS Code with GitHub Copilot), and every request to Context7 is attributed to that individual through the `oid` claim on their Entra access token. + +The gateway uses an On-Behalf-Of (OBO) flow: clients acquire a token for the APIM gateway, APIM exchanges it via Entra for a token targeting your MCP API, and the resulting token is forwarded to `mcp.context7.com`. Context7 validates the token against your tenant configuration and resolves the user. APIM remains the network and audit boundary; MFA and Conditional Access continue to be enforced by Entra at sign-in. + +## Architecture + +```mermaid +sequenceDiagram + participant Client as MCP Client + participant APIM as Azure APIM + participant Entra as Microsoft Entra + participant Context7 as mcp.context7.com + + Client->>Entra: Acquire token for APIM Gateway app + Entra-->>Client: JWT (aud = Gateway, scp = Mcp.Gateway.Access) + + Client->>APIM: Request + Bearer token + APIM->>APIM: validate-azure-ad-token
(aud = Gateway) + APIM->>Entra: OBO exchange
(scope = MCP API) + Entra-->>APIM: JWT (aud = MCP API, scp = mcp.access) + APIM->>APIM: Cache OBO token per user oid + + APIM->>Context7: Forward request + new Bearer token + Context7->>Context7: Validate against tenant config
Resolve oid to user + Context7-->>APIM: Response + APIM-->>Client: Response +``` + +## Before you start + +You will need: + +- An **Azure subscription** in the same tenant as your Entra users. +- A **Microsoft Entra admin** who can register applications and grant tenant-wide consent. +- A **Context7 enterprise teamspace**. The dashboard surfaces the Entra ID configuration card only for enterprise and enterprise-trial teamspaces. +- The **Azure CLI** installed locally (`brew install azure-cli` on macOS) and authenticated with `az login`. + +Plan for about 45 to 60 minutes end-to-end on a clean Azure subscription. + +## Part 1: Provision API Management + +APIM Basic v2 provisions in about 5 minutes and supports MCP routing. Consumption tier does **not** support MCP backends. + +Create a Bicep file: + +```bicep apim.bicep +param name string +param location string +param publisherEmail string +param publisherName string + +resource apim 'Microsoft.ApiManagement/service@2024-05-01' = { + name: name + location: location + sku: { + name: 'BasicV2' + capacity: 1 + } + properties: { + publisherEmail: publisherEmail + publisherName: publisherName + } +} + +output gatewayUrl string = apim.properties.gatewayUrl +``` + +Deploy it: + +```bash +RG=rg-context7-mcp +LOC=westeurope +APIM=apim-context7-$(openssl rand -hex 3) + +az group create -n $RG -l $LOC +az deployment group create -g $RG --template-file apim.bicep \ + --parameters name=$APIM location=$LOC \ + publisherEmail=you@example.com publisherName="Your Org" +``` + +Capture the gateway URL: + +```bash +APIM_HOST=$(az apim show -g $RG -n $APIM --query gatewayUrl -o tsv) +echo $APIM_HOST # https://.azure-api.net +``` + +## Part 2: Register Entra applications + +Two Entra app registrations are required: one representing the MCP API (the protected resource), and one representing the APIM gateway (the OBO intermediary). + +### Step 1: Register the MCP API app + +This app represents Context7's MCP server in your tenant. Issued tokens will carry its Application (client) ID as the `aud` claim. + +1. **Microsoft Entra admin center** → **App registrations** → **+ New registration**. + - **Name:** `Context7 MCP API` + - **Supported account types:** Single tenant only (formerly labelled "Accounts in this organizational directory only") + - **Redirect URI:** leave blank + - **Register** + +2. Copy the **Application (client) ID** from the Overview page. You will provide it to Context7 in Part 4. + +3. **Expose an API** → **Add** next to "Application ID URI" → accept the default `api://` → **Save**. + +4. **+ Add a scope**: + - **Scope name:** `mcp.access` + - **Who can consent:** Admins and users + - **Admin consent display name:** `Access Context7 MCP server` + - **State:** Enabled + - **Add scope** + +5. **Manifest** → set `requestedAccessTokenVersion: 2` under the `api` object. Save. + + + This forces v2 tokens with `iss: https://login.microsoftonline.com//v2.0`. v1 tokens use a different issuer and fail validation at the Context7 backend. + + +### Step 2: Register the APIM Gateway app + +This app represents the gateway as an Entra resource. Clients request tokens for it; APIM exchanges them for MCP API tokens. + +1. **App registrations** → **+ New registration**. + - **Name:** `Context7 APIM Gateway` + - **Supported account types:** Single tenant only (formerly labelled "Accounts in this organizational directory only") + - **Register** + +2. Copy the **Application (client) ID** and **Directory (tenant) ID** from the Overview page. + +3. **Certificates & secrets** → **+ New client secret** → set an expiry → **Add**. Copy the **Value** column immediately; it is only shown once. + +4. **Expose an API** → **Add** next to "Application ID URI" → accept the default → **Save**. + +5. **+ Add a scope**: + - **Scope name:** `Mcp.Gateway.Access` + - **Who can consent:** Admins and users + - **State:** Enabled + - **Add scope** + +6. **Manifest** → set `requestedAccessTokenVersion: 2`. Save. + + + The Manifest UI sometimes silently fails to persist this value. If you see v1 tokens (`iss: https://sts.windows.net/...` or `ver: 1.0`) after setting it, apply it via CLI instead: + + ```bash + az ad app update --id --set api.requestedAccessTokenVersion=2 + az ad app show --id --query api.requestedAccessTokenVersion -o tsv # should print 2 + ``` + + Do the same for the MCP API app from Step 1 if its tokens come back as v1. + + +7. **Authentication** → **+ Add a platform** → **Web** → enter `https://vscode.dev/redirect` as the redirect URI → **Configure**. + + + VS Code with GitHub Copilot uses Microsoft's hosted OAuth broker at `vscode.dev/redirect` rather than a local loopback URI. The redirect URI must be registered on the Gateway app or the sign-in flow fails with `AADSTS500113` or `AADSTS50011`. Add additional redirect URIs (or platforms) here for other MCP clients as you adopt them. Each client tool's documentation lists its expected URI. + + +### Step 3: Wire the permission chain + +The APIM Gateway app must be allowed to call the MCP API on a user's behalf, and the MCP client tools must be allowed to call the Gateway. + +In the **Context7 APIM Gateway** app: + +1. **API permissions** → **+ Add a permission** → **My APIs** → `Context7 MCP API` → **Delegated permissions** → check `mcp.access` → **Add permissions**. +2. Click **Grant admin consent for ``** at the top of the permissions table. +3. **Expose an API** → **Authorized client applications** → **+ Add a client application**. For each MCP client tool you want to allow, add its client ID and tick the `Mcp.Gateway.Access` scope: + - **VS Code with GitHub Copilot:** `aebc6443-996d-45c2-90f0-388ff96faa56` (Microsoft's well-known VS Code client ID). + - **Other tools:** check the tool's documentation for its published OAuth client ID. + +In the **Context7 MCP API** app: + +1. **Expose an API** → **Authorized client applications** → **+ Add a client application**. Add the **Context7 APIM Gateway** app's client ID and tick the `mcp.access` scope. This skips the end-user consent prompt during the OBO exchange. + +## Part 3: Configure API Management + +### Step 1: Store credentials as named values + +```bash +az apim nv create -g $RG --service-name $APIM \ + --named-value-id entra-tenant-id \ + --display-name entra-tenant-id \ + --value "" + +az apim nv create -g $RG --service-name $APIM \ + --named-value-id apim-gateway-app-id \ + --display-name apim-gateway-app-id \ + --value "" + +az apim nv create -g $RG --service-name $APIM \ + --named-value-id apim-gateway-client-secret \ + --display-name apim-gateway-client-secret \ + --value "" \ + --secret true + +az apim nv create -g $RG --service-name $APIM \ + --named-value-id mcp-api-app-id \ + --display-name mcp-api-app-id \ + --value "" +``` + + +For production, back the client secret with Azure Key Vault rather than storing the value inline. Update the named value to reference a Key Vault secret and grant APIM's managed identity `get` access to the vault. + + +### Step 2: Create the API and the MCP operation + +```bash +az apim api create -g $RG --service-name $APIM \ + --api-id context7-mcp \ + --display-name "Context7 MCP" \ + --path context7 \ + --service-url https://mcp.context7.com \ + --protocols https \ + --subscription-required false + +az apim api operation create -g $RG --service-name $APIM \ + --api-id context7-mcp \ + --operation-id post-mcp \ + --display-name "MCP" \ + --method POST \ + --url-template "/mcp" +``` + +### Step 3: Attach the OBO policy + +Save the following as `policy.xml`: + +```xml policy.xml + + + + + + + {{apim-gateway-app-id}} + + + + Mcp.Gateway.Access + + + + + + + + + + + + + + + + + @("https://login.microsoftonline.com/" + (string)context.Variables["entraTenantId"] + "/oauth2/v2.0/token") + POST + + application/x-www-form-urlencoded + + @{ + var auth = context.Request.Headers.GetValueOrDefault("Authorization", ""); + var inbound = auth.StartsWith("Bearer ") ? auth.Substring(7) : auth; + var pairs = new System.Collections.Generic.Dictionary<string, string> { + { "grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer" }, + { "client_id", (string)context.Variables["gatewayAppId"] }, + { "client_secret", (string)context.Variables["gatewaySecret"] }, + { "assertion", inbound }, + { "scope", "api://" + (string)context.Variables["mcpApiAppId"] + "/.default" }, + { "requested_token_use", "on_behalf_of" } + }; + var parts = new System.Collections.Generic.List<string>(); + foreach (var kv in pairs) { + parts.Add(System.Net.WebUtility.UrlEncode(kv.Key) + "=" + System.Net.WebUtility.UrlEncode(kv.Value)); + } + return string.Join("&", parts); + } + + + + + + + + + + @("Bearer " + (string)context.Variables["oboToken"]) + + + + + + + + + + + + + +``` + + +Two XML quirks the policy works around: + +1. **Named values do not substitute inside policy expressions.** `{{...}}` is substituted by APIM only in plain element/attribute text. References inside a `@{...}` or `@(...)` expression are treated as literal C# strings. Pull each named value into a `context.Variables` slot with an attribute-form `` block, then reference the variable inside the expression. +2. **Attribute values cannot contain raw `"`, `<`, `>`, or `&`.** Use `"`, `<`, `>`, `&` in attribute-form expressions. Element content (like ``) only needs to escape `<`, `>`, and `&`; double quotes are fine. CDATA sections also avoid escaping but disable named-value substitution, so prefer plain element content with escapes. + + +Apply it via the management REST API. `jq` wraps the policy XML in the JSON envelope the management API expects, written to `policy-body.json`: + +```bash +SUB=$(az account show --query id -o tsv) + +jq -Rs '{properties: {value: ., format: "xml"}}' policy.xml > policy-body.json + +az rest --method put \ + --uri "https://management.azure.com/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.ApiManagement/service/$APIM/apis/context7-mcp/policies/policy?api-version=2024-05-01" \ + --body @policy-body.json +``` + + +The cache duration (`3000` seconds) is slightly below Entra's default access token lifetime of one hour. Adjust if your Conditional Access policies issue shorter-lived tokens. The cache key includes the `oid` claim so each user's OBO token is isolated. + + +## Part 4: Onboard your tenant in Context7 + +Context7 validates inbound tokens in two stages: first the token's signature, audience, issuer, and scope are checked against your teamspace's tenant configuration; then the token's `oid` claim is resolved against a list of pre-provisioned users for the teamspace. **Both checks are mandatory.** Any developer who has not been added to the teamspace's user list will be rejected with `401` even when their token is otherwise valid. + +An owner or admin of the teamspace configures both from the dashboard. Users can be added one at a time (Step 2) or synced automatically from an Entra security group (Step 3). + +### Step 1: Configure the tenant + +1. Sign in to [context7.com/dashboard](https://context7.com/dashboard) and select the teamspace that will own the integration. +2. **Settings** tab → **Microsoft Entra ID** card → **Configure**. + + + The Settings tab itself is visible only for enterprise teamspaces and active enterprise trials. If you don't see it, confirm the selected teamspace is on an enterprise plan. + + +3. Fill in: + - **Tenant ID:** your Entra directory ID + - **Audience:** the **MCP API app** Application (client) ID (the second token's audience, not the gateway app) + - **Required scope:** `mcp.access` + +4. Click **Test connection**. Context7 fetches your tenant's OpenID Connect discovery document from Microsoft and confirms the issuer matches. + +5. **Save**. + +### Step 2: Pre-provision your developers + +After saving the tenant configuration, scroll down to the **Microsoft Entra ID users** card on the same Settings tab. This is where you list every Entra user who should be able to authenticate to the teamspace through APIM. + +1. Click **Add user**. +2. Enter the user's: + - **Email:** the address they sign in to Entra with. + - **Object ID (oid):** their Entra object ID. Find it in the Entra admin center under **Users → `` → Overview → Object ID**, or have the user run `az ad signed-in-user show --query id -o tsv` after `az login`. +3. Click **Add user** to save. + +Context7 creates a Clerk user record for the developer, adds them as a `developer` member of the teamspace, and inserts a `(tenant, oid, teamspace)` mapping. The same email can be added to multiple teamspaces; the Clerk user is reused and a separate mapping row is created per teamspace. + + +Clicking **Remove** on the Microsoft Entra ID card removes both the tenant configuration **and** all provisioned users for the teamspace in a single step. If you only need to revoke a single user, remove them from the Microsoft Entra ID users card instead. + + + +Each MCP API app (audience) can be configured for **one** teamspace at a time. If you reuse an audience already claimed by a different teamspace you will see "This audience is already configured for another teamspace". Open the other teamspace's Settings tab and remove the Entra configuration there first, or register a new MCP API app for this teamspace. + + + +For more than a handful of developers, prefer **Step 3: Auto-provision from an Entra security group** below. Adds and revokes track group membership automatically. CSV bulk-import and SCIM provisioning remain on the roadmap; reach out to [context7@upstash.com](mailto:context7@upstash.com) if your scale needs either ahead of general availability. + + +### Step 3: Auto-provision from an Entra security group (optional) + +For teams of more than a handful of developers, Context7 can sync the teamspace's user list directly from a Microsoft Entra security group. Members added to the group are added to the teamspace automatically; members removed from the group have their access revoked. The sync runs every 30 minutes; an admin can also trigger an immediate sync from the dashboard. + +The integration uses Microsoft Graph with **Workload Identity Federation** (WIF). Context7 acts as an OIDC issuer and signs short-lived JWT assertions that your sync app trusts via a federated credential. No shared secret is stored, rotated, or exchanged on either side. + +1. **Add Microsoft Graph permissions** to an Entra app registration. + + The simplest path is to reuse the **Context7 MCP API** app from [Part 2 Step 1](#step-1-register-the-mcp-api-app): federated identity holds no secret, so reusing it adds no risk. Open that app and add: + + - **API permissions** → **+ Add a permission** → **Microsoft Graph** → **Application permissions**. + - Search and tick `GroupMember.Read.All` and `User.ReadBasic.All`. + - **Add permissions**, then click **Grant admin consent for ``** at the top of the list. + + + Both permissions are required. `GroupMember.Read.All` alone returns each user's `oid` with all profile fields nulled out, so the sync can't resolve them to emails and drops them, surfacing as `0 members` synced. `User.ReadBasic.All` populates `mail`, `userPrincipalName`, and `displayName`. + + +2. **Add a federated credential.** + + On the same app: **Certificates & secrets** → **Federated credentials** tab → **+ Add credential** → **Federated credential scenario: Other issuer**. Open the Context7 dashboard alongside the Entra portal. The **Auto-provisioning from Entra group** card surfaces three values with copy buttons. Paste them as: + + - **Issuer**: `https://context7.com` + - **Type**: Explicit subject identifier + - **Value**: `teamspace:` (copy verbatim from the dashboard) + - **Audience**: `api://AzureADTokenExchange` + - **Name**: any label (e.g. `Context7-sync`). + + **Add**. No client secret is generated. + +3. **Create or pick an Entra security group** containing the developers who should have access. + + Entra admin center → **Groups** → **+ New group** (type *Security*, membership type *Assigned*). Add developers as **Members**, not Owners. Graph's `/members` endpoint doesn't include group owners by default. + + Open the group → **Overview** → copy the **Object ID**. + +4. **Configure in the Context7 dashboard.** + + Settings tab → **Microsoft Entra ID users** card → **Auto-sync from Entra group** panel → **Configure**. + + - **Sync app client ID**: the app you set up in step 1 (the MCP API app's client ID if you reused it). + - **Group object ID**: from step 3. + - Leave **Revoke access when a user is removed from the group** and **Run sync on schedule** ticked. + - Click **Test connection**. Expected response: *"Connected. Group has N members."* + - **Save**. + +5. **Click "Sync now"** to provision the current group members immediately. Each appears in the **Microsoft Entra ID users** list with a **Synced** badge. Subsequent syncs run every 30 minutes. + + +Manually-added users (Step 2) and synced users (Step 3) coexist on the same teamspace. The sync reconciler only touches rows whose provisioning source is `graph_group_sync`, so removing someone from the Entra group never revokes a manually-added user. + + + +If you want strict separation of concerns, register a dedicated **Context7 Sync** app instead of reusing the MCP API app. Add the same two Graph permissions and the same federated credential to it, and use its client ID in step 4. The choice is purely organizational; both produce identical sync behavior. + + + +Nested groups are not expanded. If `Context7 MCP Users` contains a subgroup `Engineering`, only direct members of `Context7 MCP Users` are synced. Flatten by adding individual members or use a single dynamic membership group. + + +The Context7 MCP server now accepts tokens whose `aud` matches the audience you provided, signed by your tenant's Entra issuer, with the required scope present, and whose `oid` matches one of the users on the teamspace's user list (manual or synced). + +## Part 5: Expose OAuth discovery for MCP clients + +For MCP clients (VS Code with GitHub Copilot, Claude Code, Cursor) to authenticate themselves without a manually-pasted Bearer token, APIM needs to advertise an OAuth 2.1 discovery surface and bridge `/authorize` and `/token` to Entra. The MCP server returns `401` with a `WWW-Authenticate` header pointing at a PRM document; clients follow the chain to obtain a token. + +### Step 1: Create the OAuth proxy API at the host root + +A second API in APIM at the root path hosts the well-known endpoints and the OAuth bridge: + +```bash +az apim api create -g $RG --service-name $APIM \ + --api-id oauth-proxy \ + --display-name "OAuth Proxy" \ + --path "" \ + --service-url "https://login.microsoftonline.com//oauth2/v2.0" \ + --protocols https \ + --subscription-required false + +for op in prm-metadata as-metadata authorize token; do + case $op in + prm-metadata) path="/.well-known/oauth-protected-resource"; method=GET ;; + as-metadata) path="/.well-known/oauth-authorization-server"; method=GET ;; + authorize) path="/authorize"; method=GET ;; + token) path="/token"; method=POST ;; + esac + az apim api operation create -g $RG --service-name $APIM \ + --api-id oauth-proxy --operation-id $op \ + --display-name "$op" --method $method --url-template "$path" +done +``` + +### Step 2: Attach the discovery + redirect policies + +Save the three policy files: + +```xml prm-policy.xml + + + + + + application/json + + { + "resource": "https:///context7", + "authorization_servers": ["https://"], + "scopes_supported": ["api:///Mcp.Gateway.Access"], + "bearer_methods_supported": ["header"] +} + + + +``` + +```xml as-metadata-policy.xml + + + + + + application/json + + { + "issuer": "https://", + "authorization_endpoint": "https:///authorize", + "token_endpoint": "https:///token", + "jwks_uri": "https://login.microsoftonline.com//discovery/v2.0/keys", + "response_types_supported": ["code"], + "grant_types_supported": ["authorization_code", "refresh_token"], + "code_challenge_methods_supported": ["S256"], + "token_endpoint_auth_methods_supported": ["none", "client_secret_post"], + "scopes_supported": ["openid", "profile", "email", "offline_access", "api:///Mcp.Gateway.Access"] +} + + + +``` + +```xml authorize-policy.xml + + + + + + @($"https://login.microsoftonline.com//oauth2/v2.0/authorize{context.Request.OriginalUrl.QueryString}") + + + + +``` + +Apply all three: + +```bash +for op in prm-metadata as-metadata authorize; do + case $op in + prm-metadata) file=prm-policy.xml ;; + as-metadata) file=as-metadata-policy.xml ;; + authorize) file=authorize-policy.xml ;; + esac + jq -Rs '{properties: {value: ., format: "xml"}}' $file > /tmp/body.json + az rest --method put \ + --uri "https://management.azure.com/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.ApiManagement/service/$APIM/apis/oauth-proxy/operations/$op/policies/policy?api-version=2024-05-01" \ + --body @/tmp/body.json +done +``` + +The `/token` operation needs no custom policy. APIM forwards POST `/token` to the service URL (`.../oauth2/v2.0/token`) with the form-encoded body and JSON response intact. + + +We use a 302 redirect on `/authorize` rather than a transparent proxy. Microsoft's sign-in page contains relative URLs and cookies tied to `login.microsoftonline.com`; proxying the HTML breaks form submissions. The redirect lands the user's browser on Microsoft's domain directly, where the sign-in flow works normally. + + +### Step 3: Add WWW-Authenticate to the MCP API on 401 + +Update the `` block in the context7-mcp policy from Part 3 so unauthorised requests carry the discovery hint: + +```xml + + + + + + Bearer resource_metadata="https:///.well-known/oauth-protected-resource" + + + + +``` + +Re-apply the policy with the same `az rest` command from Part 3. + +### Step 4: Verify the discovery surface + +```bash +curl -s "https:///.well-known/oauth-protected-resource" +curl -s "https:///.well-known/oauth-authorization-server" + +curl -i -o /dev/null -w "%{http_code} -> %{redirect_url}\n" \ + "https:///authorize?client_id=&response_type=code&redirect_uri=http%3A%2F%2F127.0.0.1%2F&code_challenge=abc&code_challenge_method=S256&scope=api%3A%2F%2F%2FMcp.Gateway.Access&state=x" + +curl -i -X POST "https:///context7/mcp" -d '{}' -H "Content-Type: application/json" 2>&1 | head -10 +``` + +Expected: +- PRM and AS metadata return the JSON documents you just defined. +- `/authorize` returns `302 Found` with a `Location` header pointing at Entra's authorize endpoint. +- An unauthorised POST to `/context7/mcp` returns `401` with `WWW-Authenticate: Bearer resource_metadata="https:///.well-known/oauth-protected-resource"`. + +## Part 6: Smoke test the gateway from CLI + +Before pointing real MCP clients at the gateway, validate the full OBO flow from your terminal. This catches misconfigurations (wrong audience, missing scope, unmapped user) without involving an MCP client. + +### Step 1: Authorize the Azure CLI on the Gateway app + +Azure CLI's well-known client ID is `04b07795-8ddb-461a-bbee-02f9e1bf7b46`. Pre-authorize it on the Gateway app's scope so `az account get-access-token` can mint tokens: + +1. Entra admin center → **App registrations** → **Context7 APIM Gateway** → **Expose an API**. +2. Under **Authorized client applications**, click **+ Add a client application**. +3. **Client ID:** `04b07795-8ddb-461a-bbee-02f9e1bf7b46`. +4. Tick the `api:///Mcp.Gateway.Access` scope. **Add**. + + +This pre-authorization is only required for the CLI smoke test described here. End users connecting via VS Code with GitHub Copilot use Microsoft's first-party VS Code client ID, which you already pre-authorized in [Part 2 Step 3](#step-3-wire-the-permission-chain). + + +### Step 2: Acquire a token and call the gateway + +```bash +GATEWAY_APP_ID= +APIM_HOST= + +az login --tenant --scope api://$GATEWAY_APP_ID/.default + +TOKEN=$(az account get-access-token --resource api://$GATEWAY_APP_ID --query accessToken -o tsv) + +curl -i -X POST "https://$APIM_HOST/context7/mcp" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}' +``` + +Expected: `200 OK`, an `mcp-session-id` response header, and a Server-Sent Events body with the Context7 server info. That confirms APIM validated your inbound token, performed the OBO exchange, forwarded the new token to `mcp.context7.com`, the MCP server validated it against your tenant configuration, and the request was attributed to your provisioned user. + +If you get a non-200 status, decode `$TOKEN` at [jwt.io](https://jwt.io) and confirm `aud` is the Gateway app's client ID, `scp` is `Mcp.Gateway.Access`, and `oid` matches the value you added under **Microsoft Entra ID users**. See [Troubleshooting](#troubleshooting) for specific error codes. + +## Part 7: Connect an MCP client + +Configure your MCP client to talk to the APIM endpoint. Example for VS Code with GitHub Copilot: + +`~/Library/Application Support/Code/User/mcp.json` on macOS (similar paths on Windows/Linux, or `.vscode/mcp.json` per workspace): + +```json +{ + "servers": { + "context7": { + "type": "http", + "url": "https:///context7/mcp" + } + } +} +``` + +Reload VS Code. The first time GitHub Copilot uses the server, the OAuth flow runs: + +1. VS Code calls `/context7/mcp` with no token. APIM returns `401` with the `WWW-Authenticate` header. +2. VS Code follows the PRM, then the AS metadata. +3. VS Code attempts Dynamic Client Registration. Because Entra ID does not implement RFC 7591, the request fails and VS Code shows a dialog: **"Dynamic Client Registration not supported. Do you want to proceed by manually providing a client registration?"** +4. Click **Copy URIs & Proceed**, then paste the **APIM Gateway app's Application (client) ID** when prompted. (This is the same app whose client secret APIM uses for the OBO call.) +5. A browser window opens. The URL bar should switch to `login.microsoftonline.com/...` after APIM's 302 redirect. Sign in with your Entra account and accept the `Mcp.Gateway.Access` consent. +6. The browser redirects to `https://vscode.dev/redirect` (VS Code's hosted OAuth broker), which hands the auth code back to your local VS Code instance. +7. VS Code exchanges the code at APIM's `/token` endpoint, which forwards the request to Entra. Entra returns an access token whose audience is the Gateway app. +8. VS Code calls `/context7/mcp` with the new token. APIM validates it, performs the OBO exchange to mint an MCP-API-audience token, and forwards to Context7. +9. The MCP server validates the OBO token against your tenant configuration and serves the request as the signed-in user. + +Trigger a Copilot Chat tool call ("use context7 to resolve the library ID for Next.js") to verify the integration. + + +The manual client ID step is required because Entra ID doesn't implement RFC 7591 Dynamic Client Registration. You can document the Gateway app's client ID in your internal onboarding guide and rotate it on the normal app-registration lifecycle. Microsoft's first-party VS Code client ID (`aebc6443-996d-45c2-90f0-388ff96faa56`) can also be used by pre-authorising it on the Gateway scope, but the Gateway app's own client ID is the most consistent path because PKCE removes the need for a client secret on the user-facing side. + + +## End-to-end token claims + +The flow produces two distinct tokens, both issued by your Entra tenant for the same user: + +| Hop | `iss` | `aud` | `oid` | `scp` | +|---|---|---|---|---| +| Client → APIM | `https://login.microsoftonline.com//v2.0` | `` | user's Entra object ID | `Mcp.Gateway.Access` | +| APIM → Context7 (after OBO) | `https://login.microsoftonline.com//v2.0` | `` | user's Entra object ID | `mcp.access` | + +Context7 validates the second token against your dashboard configuration and resolves `oid` to a user in your teamspace. + +## Troubleshooting + +### `401 Unauthorized` at APIM + +The inbound token failed `validate-azure-ad-token`. Decode it at [jwt.io](https://jwt.io) and check: + +- `iss` is `https://login.microsoftonline.com//v2.0`. If it is `https://sts.windows.net//`, the APIM Gateway app's manifest needs `requestedAccessTokenVersion: 2`. +- `aud` equals the **APIM Gateway** app's client ID, not the MCP API app's. +- `scp` contains `Mcp.Gateway.Access`. +- `exp` is in the future. + +### OBO exchange returns `AADSTS50013` or `AADSTS65001` + +The APIM Gateway app is not authorised to call the MCP API on a user's behalf. In the APIM Gateway app, verify the **API permissions** tab lists `Context7 MCP API → mcp.access (Delegated)` with **Granted for ``**. If admin consent has not been granted, run **Grant admin consent**. + +### OBO exchange returns `AADSTS70011: Invalid scope` + +The `scope` parameter in the OBO request is malformed. Verify that the `mcp-api-app-id` named value contains the **MCP API** app's client ID (a GUID) and that the policy expression renders `api:///.default`. + +### `401 Unauthorized` from Context7 with a valid OBO token + +Either the token does not match the teamspace's tenant configuration, or the user is not on the teamspace's pre-provisioned list. + +First open **Settings → Microsoft Entra ID** in the dashboard and verify: + +- **Tenant ID** matches the OBO token's `tid` claim. +- **Audience** matches the OBO token's `aud` claim exactly (case-sensitive, GUID form for v2 tokens). +- **Required scope** matches a value in the token's `scp` claim. + +Use **Test connection** to confirm the tenant is reachable. + +If the tenant config is correct, the user's `oid` is probably not in the teamspace's provisioned users list. Decode the OBO token at [jwt.io](https://jwt.io) and copy the `oid` claim, then check that exact value appears in **Settings → Microsoft Entra ID users**. If it's missing, add the user (see Part 4 Step 2). + +### Streaming responses get cut off + +APIM diagnostics with "Number of payload bytes to log" set above zero truncate MCP's Server-Sent Events stream. Set Frontend Response payload logging to `0` at the service level. + +### Wrong client ID returned to MCP clients + +If a client signs in but receives `AADSTS65005: The resource is disabled` or similar, the client's app ID is not in the APIM Gateway app's **Authorized client applications** list for the `Mcp.Gateway.Access` scope. Add it explicitly. + +### Auto-sync reports "0 members" but the group has members + +Two common causes, in order of likelihood: + +1. **The sync app is missing `User.ReadBasic.All`.** With only `GroupMember.Read.All`, Microsoft Graph returns each user's `oid` but with `mail`, `userPrincipalName`, and `displayName` set to `null`. Context7 drops users without a resolvable email. The dashboard surfaces this as the error message: *"Graph returned N user members but their profile fields are null. Sync app needs User.ReadBasic.All in addition to GroupMember.Read.All."* Add `User.ReadBasic.All` to the sync app's API permissions and grant admin consent. + +2. **The users are group Owners, not Members.** Open the group in Entra → **Members** tab (not Owners) → verify the people you expect to sync are listed there. Add them as Members if they're only Owners. + +### `AADSTS500113: No reply address is registered for the application` + +The Gateway app has no redirect URIs registered. VS Code's OAuth flow sends `https://vscode.dev/redirect` as the redirect URI, and Entra rejects the request when that URI isn't on the app. Open the Gateway app in Entra → **Authentication** → **+ Add a platform** → **Web** → add `https://vscode.dev/redirect` → **Configure**. See [Part 2 Step 2](#step-2-register-the-apim-gateway-app). + +### `AADSTS50011: The redirect URI ... does not match` + +A specific redirect URI was sent that the Gateway app doesn't have on its list. Read the error message to see exactly which URI Entra received (most commonly `https://vscode.dev/redirect`), then add it under the Gateway app's **Authentication** → **+ Add a platform** → **Web**. + +## What this does not cover + +- **On-premise MCP server.** This guide proxies the hosted `mcp.context7.com`. For air-gapped or compliance scenarios where MCP traffic cannot leave your network, contact [context7@upstash.com](mailto:context7@upstash.com). +- **Dynamic Client Registration.** Entra does not implement RFC 7591. Each approved MCP client must be pre-registered (or use a Microsoft first-party client ID) and pre-authorized on the APIM Gateway app's scope. +- **Group-based authorization at Context7.** Context7 resolves the `oid` claim to a user record and authorises against teamspace membership. Group-based policies inside Context7 (for example, restricting which Entra group can use which libraries) are not configured by this guide; reach out if your team needs that level of control. diff --git a/docs/enterprise/enterprise-managed-auth/okta.mdx b/docs/enterprise/enterprise-managed-auth/okta.mdx new file mode 100644 index 0000000..83c7c5d --- /dev/null +++ b/docs/enterprise/enterprise-managed-auth/okta.mdx @@ -0,0 +1,129 @@ +--- +title: "Enterprise-Managed Auth with Okta" +sidebarTitle: "Okta" +description: "Centrally authorize the Context7 MCP server for your organization through Okta Cross-App Access, so developers connect on first login with no per-user OAuth." +--- + +Enterprise-Managed Auth (EMA) lets your Okta administrators decide who can use the Context7 MCP server, in the same console where you manage every other app. Developers sign in once with their corporate Okta account and their MCP client is connected automatically. There is no per-user OAuth consent and no API keys to distribute. + +It implements the MCP [Enterprise-Managed Authorization](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization) extension: Okta issues a short-lived Identity Assertion (ID-JAG) for the user, Context7 validates it against your Okta tenant, and resolves the user to your teamspace by email. + + +Enterprise-Managed Auth currently works with **Claude Code** as the MCP client. + + + +Okta Cross-App Access (the productized ID-JAG flow) is an Early Access feature. Enable it from **Admin Console → Settings → Features** before you start. EMA also requires a Context7 enterprise teamspace. + + +## How it works + +- A developer signs in to their MCP client with your Okta org. +- The client asks Okta for an ID-JAG scoped to Context7. Okta applies your access policy (group, role, conditional access) and issues it only if the user is allowed. +- The client exchanges the ID-JAG with Context7 for an access token, then calls `mcp.context7.com`. +- Context7 validates the ID-JAG against your tenant and, on first sign-in, provisions the user as a teamspace member automatically (matched by email). + +Access is governed entirely in Okta. There is no user list to maintain in Context7: anyone your admin assigns to the connected app is provisioned on first sign-in. Removing them from the app blocks new sign-ins immediately, and any active session ends when its short-lived access token expires (within an hour). + +## Before you start + +- An **Okta org** with **Cross App Access** enabled. +- A **Context7 enterprise teamspace**. The Enterprise-Managed Auth settings appear only for enterprise plans. +- Developers assigned to the connected Okta app. They are provisioned into the teamspace automatically on first sign-in, so there is no manual user list to maintain. + +## Part 1: Configure Okta + +### Step 1: Enable Cross App Access + +In the **Admin Console**, go to **Settings → Features**, find **Cross App Access** under Early Access, and turn it on. + + + ![Cross App Access toggle in Okta Admin Console Settings → Features](/images/enterprise/enterprise-managed-auth/okta-enable-feature.png) + + +### Step 2: Add Context7 as a resource app + +Go to **Applications → Applications → Browse App Catalog**, search for **XAA Resource App**, and click **Add Integration**. + +- **Application label:** `Context7` +- **Issuer URL:** `https://context7.com` + +Click **Done**. + + + ![Add XAA Resource App general settings with Context7 label and issuer URL](/images/enterprise/enterprise-managed-auth/okta-resource-app.png) + + +### Step 3: Add your MCP client as a requesting app + +Browse the catalog again, search for **XAA Requesting App**, and click **Add Integration**. + +- **Application label:** a name for the MCP client (for example `MCP Client`) +- **Issuer URL:** `https://context7.com` +- **Client ID:** the client identifier the MCP client uses (for example `mcpclient-at-context7`) + +Click **Done**, then open the **Sign On** tab and note the Client ID and secret if your client needs them. + + + ![Add XAA Requesting App general settings with label, issuer URL, and client ID](/images/enterprise/enterprise-managed-auth/okta-requesting-app.png) + + +### Step 4: Connect the two apps + +Open the requesting app → **Manage Connections** tab. Under **Apps providing consent**, choose **Add resource apps**, select **Context7**, and **Save**. + + + ![Manage Connections tab linking the MCP Client to the Context7 resource app](/images/enterprise/enterprise-managed-auth/okta-manage-connections.png) + + +### Step 5: Assign your users + +On both apps, open the **Assignments** tab and assign the people (or groups) who should have access. Only assigned users can obtain an ID-JAG. + + + ![Assignments tab assigning a user to the app](/images/enterprise/enterprise-managed-auth/okta-assignments.png) + + +## Part 2: Configure Context7 + +Sign in to [context7.com/dashboard](https://context7.com/dashboard), select your enterprise teamspace, open the **Enterprise** tab, and select **Okta**. + +- **Identity provider issuer:** your Okta org issuer, for example `https://.okta.com`. +- **Scope** (optional): scopes to grant on the issued access token. Leave blank to pass through whatever Okta authorizes. + +Click **Configure**, enter the issuer, and **Save**. Context7 validates the issuer against your tenant's OpenID Connect metadata on save. + + + ![Context7 dashboard Enterprise-Managed Auth settings card with the Okta issuer field](/images/enterprise/enterprise-managed-auth/context7-ema-config.png) + + + +Use your **org** authorization server issuer (`https://.okta.com`), not a custom authorization server. Cross-App Access apps cannot use custom authorization servers. + + +## Part 3: How developers connect + +Enterprise-Managed Auth is wired on the **client** side by your organization, not per developer. The Okta sign-in isn't triggered by a server URL someone pastes. It happens because Claude Code is configured to use your enterprise IdP for managed connectors. + +Your admin connects the Okta org to Claude and enables the Context7 MCP server (`https://mcp.context7.com/mcp`) as a managed connector. After that, anyone using Claude Code with their corporate Okta identity gets Context7 automatically: Claude Code obtains an ID-JAG from Okta and exchanges it with Context7 for an access token. There is no token to paste and no per-user OAuth. + +See Claude's [Enterprise-Managed Auth](https://claude.com/blog/enterprise-managed-auth) documentation for the client-side admin setup. + +## Troubleshooting + +### `unauthorized_client` / "client cannot use a custom authorization server" + +The sign-in or token-exchange used a custom authorization server. Use the org authorization server endpoints (`https://.okta.com/oauth2/v1/...`). + +### A valid Okta user can't be provisioned + +Context7 provisions members from the `email` claim on the ID-JAG, so the connected app must request the `email` scope at sign-in (it's included in the setup above). If provisioning still fails, the teamspace may be at its member limit. + +### The user receives no token at all + +The user is not assigned to the connected apps in Okta, or the connection between the requesting and resource apps was not saved. Re-check Steps 4 and 5. + +## What this does not cover + +- **Identity providers other than Okta.** EMA currently supports Okta as the IdP. For Microsoft Entra, see [Microsoft Entra ID](/enterprise/enterprise-managed-auth/entra). +- **Group-based authorization inside Context7.** Okta decides who can obtain a token; Context7 authorizes against teamspace membership. Restricting which libraries a group can access is not configured here. diff --git a/docs/enterprise/gitops.mdx b/docs/enterprise/gitops.mdx new file mode 100644 index 0000000..64d147f --- /dev/null +++ b/docs/enterprise/gitops.mdx @@ -0,0 +1,148 @@ +--- +title: "GitOps" +sidebarTitle: "GitOps" +description: "Manage the list of indexed repositories declaratively from a Git repo and reconcile your on-premise instance to match it" +--- + +GitOps lets you keep the list of sources Context7 indexes in a Git repository, instead of adding them one by one in the dashboard. Alongside Git repositories, a source can be a Confluence space, a website, an llms.txt index, or an OpenAPI specification. Context7 reads a manifest file from that repo and reconciles its own state to match: it indexes anything new, re-indexes anything whose settings changed, and (optionally) removes anything you have deleted from the manifest. + +The point is to keep your configuration in code. After a disaster, or when standing up a second environment, you point a fresh instance at the manifest repository and the entire index rebuilds itself with no manual clicks. + + + ![The GitOps settings card under Settings, Indexing](/images/enterprise/gitops/gitops-settings.png) + + +## Before you start + +GitOps clones your manifest repository and the repositories it indexes using the Git credentials you configure under **Settings → Integrations**. Connect a GitHub App or a personal access token first; see [GitHub Integration](/enterprise/integrations/github). Automatic syncs on every push require the **GitHub App** (a personal access token cannot receive webhooks). + + +If you set up the GitHub App **before** GitOps was available, it is not subscribed to push events and will not trigger syncs. Add the **push** event to the App on GitHub, or recreate it from **Settings → Integrations**. See [GitHub Integration](/enterprise/integrations/github#webhooks). + + +## How it works + +You commit a manifest file (by default `repos.yaml`) to a Git repository. Context7 clones that repository using the same Git credentials you already configured under **Settings → Integrations** (a GitHub App or a personal access token), reads the manifest, and compares it against the repositories it currently has indexed. + +For each source in the manifest, Context7 decides what to do: + +- **Add** it if it is in the manifest but not yet indexed. +- **Re-index** it if its manifest entry changed, for example a different branch, new folder filters, or a changed page limit, or if its last indexing run did not finish. +- **Leave it untouched** if it already matches. Running a sync with no changes is a safe no-op. + +When pruning is enabled, repositories that you remove from the manifest are also deleted from the instance. Pruning only ever removes repositories that GitOps itself added; repositories you add by hand in the dashboard are never touched. + + +GitOps is the source of truth only for the repositories listed in the manifest. You can still add other repositories manually in the dashboard, and they will be left alone during a sync. + + +## The manifest file + +The manifest is a YAML file with a list of sources under `repos`. An optional `defaults` block applies to every entry unless an entry overrides it. + +An entry's `type` selects which parser handles it. Omit `type` and the entry is treated as a Git repository, so manifests written before multi-source support keep working unchanged. + +```yaml repos.yaml +defaults: + indexSourceCode: false + branch: "" # empty means the repository's default branch +repos: + # Git repository (the default when type is omitted) + - url: https://github.com/acme/payments + branch: main + folders: [docs] + excludeFolders: [node_modules] + + # Confluence space (uses the connection from Settings → Integrations) + - url: https://acme.atlassian.net/wiki + type: confluence + spaceKey: TEAM + + # llms.txt index + - url: https://docs.acme.com/llms.txt + type: llmstxt + + # Website crawl + - url: https://docs.acme.com/ + type: website + maxPages: 200 + + # OpenAPI specification + - url: https://petstore.swagger.io/v3/openapi.json + type: openapi +``` + +Every entry needs a `url` (or `repoUrl`). The remaining fields depend on `type`: + +| `type` | Fields | +| ------ | ------ | +| `git` (default) | `branch`, `folders`, `excludeFolders`, `excludeFiles`, `indexSourceCode` — the same options as the **Add Repository** form. | +| `confluence` | `spaceKey` (required), `spaceId` (Cloud only, resolved automatically from the key when omitted), `spaceName`, `title`, `description`. The whole space is indexed. | +| `website` | `maxPages`, `maxDepth`, `excludePatterns`, `title`, `description`. | +| `llmstxt` | `maxPages`, `title`, `description`. The URL must point to an `llms.txt`, `llms-full.txt`, or `llms-small.txt` file. | +| `openapi` | `title`, `description`. | + + +Confluence entries reuse the site URL and API token you set under **Settings → Integrations → Confluence**, so no credentials go in the manifest. Website, llms.txt, and OpenAPI sources are fetched over public HTTP and need no credentials. Configure Confluence before adding Confluence entries, or the sync reports those entries as failed. + + +The manifest is validated strictly: an unknown `type`, a field that does not belong to the entry's type (a common source of silent mistakes), or a missing required field rejects the **whole** sync. Nothing changes until the file parses cleanly, so a malformed manifest can never partially apply or wipe your index. + +## Configuring in the dashboard + +Open **Settings → Indexing → GitOps**, fill in the manifest repository, and save. + +| Setting | Description | +| ------- | ----------- | +| Enable GitOps sync | Turns on automatic reconciliation (on startup, on the schedule, and on push). When off, nothing syncs automatically, but you can still run a sync by hand. | +| Manifest repository URL | The Git repository that holds the manifest. | +| Manifest path | Path to the manifest within that repository. Defaults to `repos.yaml`. | +| Branch | Branch to read the manifest from. Leave blank for the default branch. | +| Sync schedule | How often to reconcile automatically. Choose a preset or enter a custom cron expression. Set to **Manual only** to disable scheduled syncs. | +| Prune removed repositories | Delete GitOps-managed repositories that are no longer in the manifest. Off by default. | + +The manifest repository is cloned with the Git token from **Settings → Integrations**, so private repositories work without any extra credentials. If you have not configured a GitHub App or personal access token for the host, the sync reports a clear error. + + +Pruning permanently deletes a repository's indexed data (snippets and embeddings). It only affects repositories GitOps added, never ones you created in the dashboard, but treat the manifest as authoritative once pruning is on. Removing an entry and syncing will delete that library. + + +## When syncs happen + +A reconcile runs in four situations: + +- **On startup.** When the instance boots with GitOps enabled, it reconciles immediately. This is what makes disaster recovery a single step: bring up a fresh instance pointed at the manifest repo and the index rebuilds itself. +- **On a schedule.** The cron schedule you set acts as a steady fallback that keeps the instance in line with the manifest. +- **On push (webhook).** If the manifest repository is on a connected GitHub App, every push triggers an immediate sync. See [Webhooks](#webhooks) below. +- **On demand.** Click **Sync now** in the dashboard, or call the API, to reconcile right away. + +Repeated syncs are cheap. Context7 remembers the last commit it processed and skips the work entirely when nothing has changed, and it only re-indexes a repository when its manifest entry actually differs. + +## Webhooks + +When the manifest repository is served by the [GitHub App](/enterprise/integrations/github), every push to its configured branch triggers an immediate sync, with no CI step required. Pushes to other repositories or other branches are ignored. + +Webhook delivery requires the GitHub App, an instance reachable from GitHub, and the App subscribed to push events. See [GitHub Integration](/enterprise/integrations/github#webhooks) for setup, including what to do if you connected the App before push support existed. With a personal access token instead of the App, webhooks are unavailable; use the sync schedule or have CI call the reconcile endpoint. + +## Disaster recovery + +Because the repository list lives in Git, rebuilding an instance does not require restoring it from a backup. Stand up a fresh Context7 instance, configure your LLM and Git credentials, enable GitOps with the manifest repository URL, and start it. On boot it reads the manifest and re-indexes every listed repository. Your configuration is reproducible from code. + +## API + +The same operations are available over the REST API and require an admin [API key](/enterprise/api/authentication). + +``` +GET /api/gitops/status # current configuration and the last sync result +PUT /api/gitops/config # update the configuration +POST /api/gitops/reconcile # run a sync now +``` + +To propagate a manifest change from CI immediately (for example when you are not using a GitHub App), call the reconcile endpoint after merging: + +```bash +curl -X POST http://localhost:3000/api/gitops/reconcile \ + -H "Authorization: Bearer " +``` + +The response reports what the sync did, including how many repositories were created, updated, left unchanged, pruned, and skipped. diff --git a/docs/enterprise/integrations/confluence.mdx b/docs/enterprise/integrations/confluence.mdx new file mode 100644 index 0000000..f8edeb9 --- /dev/null +++ b/docs/enterprise/integrations/confluence.mdx @@ -0,0 +1,84 @@ +--- +title: "Confluence Integration" +sidebarTitle: "Confluence" +description: "Index Confluence spaces from Atlassian Cloud or a self-hosted Data Center instance" +--- + +Context7 can index the pages of a Confluence space and serve them like any other library. It works with **Atlassian Cloud** and with self-hosted **Data Center / Server**. + +An admin connects Confluence once under **Settings → Integrations** using an API token. After that, anyone who can add libraries picks a space and pages from **Add → Confluence**. There is no OAuth app to register, which keeps the setup self-contained on your own infrastructure. + + +Confluence pages are behind authentication, so Context7 reaches them with the token you configure. The token needs read access to the spaces you want to index. + + +## Connect Confluence + +Open **Settings → Integrations → Confluence**, choose your deployment, fill in the fields, and use **Test connection** to confirm before saving. + + + ![Confluence integration settings with the Data Center deployment selected](/images/enterprise/integrations/confluence-settings.png) + + + + + | Field | Value | + | ----- | ----- | + | Deployment | Cloud | + | Site URL | `https://your-company.atlassian.net` | + | Email | The account email that owns the token | + | API Token | Create one at [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens) | + + Cloud uses the Confluence v2 REST API and authenticates with the email and API token together. + + + | Field | Value | + | ----- | ----- | + | Deployment | Data Center | + | Site URL | `https://confluence.your-company.com` (include the context path if your install uses one, for example `/confluence`) | + | Email | Leave blank | + | Personal Access Token | Create one in Confluence under your profile, **Personal Access Tokens** | + + Data Center uses the v1 REST API and authenticates with a Personal Access Token. Personal Access Tokens require Confluence 7.9 or later. If your instance uses basic auth instead, put the username in the Email field and the password in the token field. + + + + +Point Context7 at a service account rather than a personal login, so indexing does not depend on one person's access. + + +## Index a space + +Go to **Add** and choose **Confluence**. + + + ![The Add Libraries source picker with a Confluence tile](/images/enterprise/integrations/confluence-source.png) + + +Pick a space, then index the whole space or choose specific pages. Give the project a title and description if you want to override the auto-detected ones, then choose **Start Parsing**. + + + ![Selecting a Confluence space and pages, with the page tree and Start Parsing button](/images/enterprise/integrations/confluence-add.png) + + + + + Choose the space from the dropdown, or paste a space URL (for example `https://your-site.atlassian.net/wiki/spaces/TEAM`) into **Space URL** to select it directly — handy when the account can read many spaces. + + + Leave **Index the entire space** on to index everything, which is the fastest path and the right choice for large spaces. Turn it off to pick individual pages: the page tree mirrors the space hierarchy, so selecting a parent selects its children. Very large spaces load their pages in batches — use **Load more pages** to fetch the rest, and the search box to filter. + + + Context7 fetches the pages, converts them to Markdown (code blocks, tables, and callouts are preserved), and indexes them. The project appears under your libraries when it finishes. + + + + +Indexing the entire space means a later refresh also picks up pages added since. Selecting a specific subset pins the project to exactly those pages. + + +You can also index Confluence spaces declaratively with [GitOps](/enterprise/gitops) — add a `type: confluence` entry with a `spaceKey` to your manifest, and it reuses this same connection. + +## Refresh and delete + +A Confluence project behaves like any other library. **Refresh** re-indexes the space using the stored selection and the current admin token, so rotating the token in Settings updates future refreshes without editing the project. **Delete** removes the project and its indexed content. diff --git a/docs/enterprise/integrations/github.mdx b/docs/enterprise/integrations/github.mdx new file mode 100644 index 0000000..7be108b --- /dev/null +++ b/docs/enterprise/integrations/github.mdx @@ -0,0 +1,107 @@ +--- +title: "GitHub Integration" +sidebarTitle: "GitHub" +description: "Connect Context7 to GitHub with a GitHub App or a personal access token for private repository access and push webhooks" +--- + +Context7 needs access to your GitHub repositories to clone and index them. You can connect GitHub in two ways: a **GitHub App** (recommended) or a **personal access token**. The GitHub App additionally delivers push webhooks, which power push-triggered [GitOps](/enterprise/gitops) syncs. + +Both are configured under **Settings → Integrations**. + + +Running GitHub Enterprise Server instead of github.com? Point Context7 at your server first. See [GitHub Enterprise Server](#github-enterprise-server). + + +## GitHub App + +The GitHub App is the recommended option. It gives Context7 fine-grained access to only the repositories you select, rotates short-lived access tokens automatically, and delivers webhooks for push-triggered GitOps syncs. + +Connecting the App is two steps: first create the App, then install it on your repositories. + + + + Go to **Settings → Integrations** and choose **Set up GitHub App**. Context7 generates a pre-filled App manifest and sends you to GitHub to create the App in one click. You are redirected back and Context7 stores everything it needs automatically: the App ID, private key, client ID and secret, and the webhook secret. + + + After it is created, install the App on the account or organization that owns your repositories, and grant it access to the repositories you want to index (including your GitOps manifest repository, if you use GitOps). + + + +Once both steps are done, the GitHub App card shows the connected App and its installation: + + + ![Connected GitHub App with one installation under Settings, Integrations](/images/enterprise/integrations/github-app.png) + + +### Verify the App configuration + +The setup flow configures everything below automatically, so a newly created App is ready to use. Use this section to confirm the App, or to fix an App you connected before GitOps existed (it will be missing the push event; see [Webhooks](#webhooks)). Open the App at `github.com/settings/apps`. + +| Setting | Required value | +| ------- | -------------- | +| Repository permission: Contents | Read-only | +| Repository permission: Metadata | Read-only (mandatory) | +| Subscribed events | Push | +| Webhook | Active | +| Webhook URL | `https:///api/github/webhook` | +| Webhook secret | Set | +| Callback URL | `https:///api/github/callback` | +| Setup URL | `https:///api/github/setup` | + +Under **Permissions & events**, the repository permissions are granted and the **Push** event is subscribed: + + + ![GitHub App repository permissions and the subscribed Push event](/images/enterprise/integrations/github-permissions.png) + + +Under **Webhook**, it is active and points at your instance with a secret configured: + + + ![GitHub App webhook settings: active, webhook URL, and a configured secret](/images/enterprise/integrations/github-webhook.png) + + +## Personal access token + +As a simpler alternative, add a GitHub personal access token under **Settings → Integrations**. Use a token with the `repo` scope for private repository access. + + + ![Git token fields under Settings, Integrations](/images/enterprise/integrations/git-tokens.png) + + +A personal access token can clone and index repositories, but it **cannot receive webhooks**. With a token only, push-triggered GitOps syncs are unavailable; use the GitOps sync schedule or trigger syncs from CI instead. + +## GitHub Enterprise Server + +Context7 works with GitHub Enterprise Server, not only github.com. Set your server host **before** you create the GitHub App or add a token, so the App is created on your own server instead of github.com. + + + + Open **Settings → Integrations → Git Tokens** and select **Using GitHub Enterprise?**. Enter your server host, for example `github.your-company.com` (no `https://`), then choose **Save & Apply**. + + + ![Git Tokens section with the Using GitHub Enterprise option under Settings, Integrations](/images/enterprise/integrations/git-tokens.png) + + + + Now follow [GitHub App](#github-app) or [Personal access token](#personal-access-token) above. The App manifest, installation, sign-in, and all API calls target your server. Before you create the App, the GitHub App card shows the server it will use, so you can confirm it is not github.com. + + + +For this to work, Context7 must reach your server's API at `https:///api/v3`, and your server must reach Context7 at its webhook URL for push delivery. + + +Prefer to set this at deploy time, for example as part of a disaster recovery rebuild? Set the `GITHUB_URL` environment variable to your server URL, such as `https://github.your-company.com`. A host saved in the UI takes precedence over the environment variable when both are set. + + +## Webhooks + +When the GitHub App is connected, GitHub delivers `push` events to `https:///api/github/webhook`. Context7 verifies each delivery's signature against the App's webhook secret and uses pushes to drive [GitOps](/enterprise/gitops) reconciliation: a push to a GitOps manifest repository triggers an immediate sync. + +For delivery to work: + +- Your instance must be **reachable from GitHub** at the webhook URL. An instance behind a firewall that GitHub cannot reach will not receive webhooks. +- The App must be **subscribed to push events** (new App setups are configured this way automatically). + + +GitHub Apps created before push support was added are not subscribed to any events, so they do not deliver webhooks. If you set up the App earlier, open it on GitHub and add the **push** event under its event subscriptions, confirm its webhook URL is `https:///api/github/webhook`, or recreate the App from **Settings → Integrations**. + diff --git a/docs/enterprise/library-import.mdx b/docs/enterprise/library-import.mdx new file mode 100644 index 0000000..0c4169f --- /dev/null +++ b/docs/enterprise/library-import.mdx @@ -0,0 +1,183 @@ +--- +title: "Library Import" +sidebarTitle: "Library Import" +description: "Move library content from Context7 Cloud into an airgapped on-premise install" +--- + +Airgapped on-premise installs can't reach Context7 Cloud, but you may still want the content of public libraries that the cloud already indexes. Library Import lets you select those libraries in the cloud dashboard, download them as a single file, and import that file into your on-premise install. + +This feature is available only to customers with an **offline (airgapped) license**. Installs running an online license fetch public library content from the cloud directly and don't need it. + +## How It Works + +The export bundle carries only snippet content, not embeddings. Embeddings are tied to a specific embedding model, so they aren't portable between deployments. When you import, your on-premise install re-embeds the snippets with its own configured embedding provider. This means imported libraries match the rest of your index and stay fully searchable, with nothing but text crossing the airgap. + +```mermaid +flowchart LR + subgraph cloud["Context7 Cloud"] + direction TB + A["Select
libraries"] --> B["Download
.zip bundle"] + end + + subgraph onprem["On-Premise install"] + direction TB + C["Upload
and import"] --> D["Re-embed
locally"] --> E["Searchable
library"] + end + + B -. "transfer
across airgap" .-> C + + classDef cloud fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a; + classDef step fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6; + classDef done fill:#dcfce7,stroke:#16a34a,color:#166534; + class A,B cloud; + class C,D step; + class E done; +``` + +## Before You Start + +- An **offline on-premise license**. The export page is only visible to accounts that hold one. +- Your on-premise **AI provider is configured** (Settings → completed setup wizard). Import re-embeds snippets, so it needs a working embedding provider. + +## Exporting from Context7 Cloud + + + + + +In the [Context7 Cloud dashboard](https://context7.com), open **More → Export Libraries**. The link only appears for accounts with an offline license. + + + ![Export Libraries link in the dashboard menu](/images/enterprise/library-import/export-menu.png) + + + + + + +Search for libraries by name and click **Add** to put them in your selection. The selection persists while you keep searching, so you can collect libraries from several searches before downloading. Remove a library from the selection with the **x** on its chip. + +You can export up to 50 libraries at once. + + + ![Searching and selecting libraries to export](/images/enterprise/library-import/export-select.png) + + + + + + +Click **Download selected**. Context7 gathers every code and info snippet for the chosen libraries and produces a single `context7-libraries.zip` file. + + + + + +## Importing on Your On-Premise Install + + + + + +Move `context7-libraries.zip` into your airgapped environment using whatever method your security policy allows. + + + + + +In your on-premise dashboard, click **Add Repo**, then choose the **Context7 Export** source. This source only appears on offline-license installs. + + + ![Context7 Export source on the Add page](/images/enterprise/library-import/import-source.png) + + + + + + +Select your `.zip` export (up to 100 MB). To replace libraries that already exist on this install, enable **Overwrite existing libraries**. Click **Import**. + + + ![Uploading a Context7 export to import](/images/enterprise/library-import/import-upload.png) + + +Each library is queued as its own job. Follow progress under the **Parse Queue** tab while snippets are re-embedded locally. + + + + + +## After Import + +Imported libraries appear in your Repositories list with an **Imported** badge and are queryable like any other library. + + + ![Imported badge on a library in the Repositories list](/images/enterprise/library-import/imported-badge.png) + + +Because your install didn't parse these libraries from source, it can't refresh them. The Refresh action is disabled for imported libraries. To update one, export a fresh bundle from Context7 Cloud and import it again with **Overwrite existing libraries** enabled. + + +Re-importing a library you already have does nothing unless **Overwrite existing libraries** is checked. The import skips libraries that already exist and tells you which ones it skipped. + + +## Automating with the API + +Besides the dashboard flow, both sides expose an API so you can script imports. For example, you can sync a fixed set of libraries into on-premise on a schedule from a bridge host that can reach both networks. + + + + + +Call the cloud export endpoint with your **enterprise license key** in the `Authorization` header. It returns one library's full content (every code and info snippet, without embeddings), already shaped for the import endpoint. + +```bash +curl -X POST https://context7.com/api/v1/enterprise/export \ + -H "Authorization: Bearer YOUR_LICENSE_KEY" \ + -H "Content-Type: application/json" \ + -d '{"library":"vercel/next.js"}' +``` + +Only public libraries can be exported this way. + + + + + +Post that JSON to your install's [import endpoint](/enterprise/api/parse/import-libraries), authenticated with a [personal API key](/enterprise/api/authentication#creating-an-api-key). The body is `{ "libraries": [...], "force": false }`, which is exactly the export response shape. + +```bash +curl -X POST https://your-instance.example.com/api/import-libraries \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + --data @library.json +``` + + + + + +From a host that can reach both networks, such as a bridge or import gateway, the two calls chain directly: + +```bash +curl -sf -X POST https://context7.com/api/v1/enterprise/export \ + -H "Authorization: Bearer YOUR_LICENSE_KEY" \ + -H "Content-Type: application/json" \ + -d '{"library":"vercel/next.js"}' \ +| curl -X POST https://your-instance.example.com/api/import-libraries \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + --data-binary @- +``` + +For a strictly airgapped install, save the export response to a file, transfer it the same way you would the `.zip`, then import it. The import endpoint also accepts the dashboard `.zip` bundle as a `multipart/form-data` upload (field `bundleFile`). See the [endpoint reference](/enterprise/api/parse/import-libraries) for details. + + +The import endpoint is available only on offline-license installs, the same gate as the dashboard flow. A library that already exists is skipped unless you overwrite it with `force`, either as a `?force=true` query param (handy when piping the export straight through) or a `"force": true` field in a JSON body. The response lists what it queued and skipped. + + +## Limits + +- Up to 50 libraries per export. +- Export files up to 100 MB per import. +- Only public libraries indexed by Context7 Cloud can be exported. diff --git a/docs/enterprise/on-premise.mdx b/docs/enterprise/on-premise.mdx new file mode 100644 index 0000000..6ce04cd --- /dev/null +++ b/docs/enterprise/on-premise.mdx @@ -0,0 +1,229 @@ +--- +title: "On-Premise Deployment" +sidebarTitle: "Getting Started" +description: "Run the full Context7 stack inside your own infrastructure, so code and documentation never leave your environment" +--- + +Context7 On-Premise lets you run the full Context7 stack inside your own infrastructure. Your code, documentation, and embeddings never leave your environment. + +## What's Included + +- Full Context7 parsing and indexing pipeline +- Local vector storage (no external vector DB required) +- Built-in MCP server. Works with any MCP-compatible AI client +- Web UI for managing indexed libraries and configuration +- REST API compatible with the public Context7 API +- Private GitHub and GitLab repository ingestion + + + ![On-Premise Architecture](/images/on-premise-architecture.png) + + +## Setup + + + + + +Go to [context7.com/plans](https://context7.com/plans) and click **On-Premise Trial**. Fill out the request form. No credit card required. You'll receive a 30-day full-featured license key via email once approved. + + + + + +Follow the deployment guide for your platform: + + + + Deploy with Docker Compose + + + Deploy on Kubernetes with raw manifests + + + + + + + +Open `http://localhost:3000` in your browser. On first launch, the setup wizard guides you through configuring: + +1. **AI Provider** - Choose OpenAI, Anthropic, Gemini, or a custom OpenAI-compatible endpoint. Enter your API key and model name. +2. **Embedding Provider** - Use the same provider as your LLM, or configure a separate one for embeddings. +3. **Git Tokens** - Add a GitHub and/or GitLab token for the platforms you use. + +All configuration is stored locally in the embedded database and can be updated later from the Settings page. + + + + + +From the dashboard, click **Add Repository** and enter a GitHub or GitLab URL. Once ingestion completes, your private docs are ready to query. + +You can also add libraries via the REST API: + +```bash +curl -X POST http://localhost:3000/api/parse \ + -H "Content-Type: application/json" \ + -d '{"url": "https://github.com/your-org/your-repo"}' +``` + + + + + +## Connecting Your AI Client + +Point your MCP client at your deployment URL. Replace `https://context7.internal.yourcompany.com` with your actual host. + +### Claude Code + +```bash +claude mcp add --scope user --transport http context7 https://context7.internal.yourcompany.com/mcp +``` + +### Cursor + +Add to `~/.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "context7": { + "url": "https://context7.internal.yourcompany.com/mcp" + } + } +} +``` + +### Opencode + +```json +{ + "mcp": { + "context7": { + "type": "remote", + "url": "https://context7.internal.yourcompany.com/mcp", + "enabled": true + } + } +} +``` + +For other clients, see [All Clients](/resources/all-clients). + +## Configuration + +### Environment Variables + +These are set in your `docker-compose.yml` or `.env` file before starting the container. + +| Variable | Required | Description | +|---|---|---| +| `LICENSE_KEY` | Yes | License key issued by Upstash | +| `PORT` | No | HTTP port (default: `3000`) | +| `DATA_DIR` | No | Data directory inside the container (default: `/data`) | + + +AI provider keys, model settings, and git tokens are **not** set via environment variables. They are configured through the setup wizard and can be updated anytime from the Settings page in the web UI. + + +### AI Provider Settings + +Configured via the **Settings** page in the web UI. + +| Setting | Description | +|---|---| +| LLM Provider | `openai`, `anthropic`, `gemini`, or custom | +| LLM API Key | API key for your chosen provider | +| LLM Model | Model name (e.g. `gpt-4o`, `claude-sonnet-4-5`, `gemini-2.5-flash`) | +| LLM Base URL | Custom OpenAI-compatible endpoint (for local models or proxies) | + +#### Examples + + + + ``` + Provider: custom + Base URL: https://openrouter.ai/api/v1 + Model: openai/gpt-4o + API Key: sk-or-v1-... + ``` + + + ``` + Provider: custom + Base URL: http://host.docker.internal:11434/v1 + Model: llama3.2 + API Key: ollama + ``` + + + +### Embedding Settings + +By default, Context7 uses the same provider as your LLM for generating embeddings. You can configure a separate embedding provider if needed. + +| Setting | Description | +|---|---| +| Embedding Provider | `openai` or `gemini` | +| Embedding API Key | Separate API key for embeddings (falls back to LLM API key) | +| Embedding Model | Embedding model name (e.g. `text-embedding-3-small`) | +| Embedding Base URL | Custom embedding endpoint | + +### Git Access Tokens + +Configured via the **Settings** page in the web UI. + +| Setting | Description | +|---|---| +| GitHub Token | GitHub Personal Access Token. Required for GitHub repositories | +| GitLab Token | GitLab token. Required for GitLab repositories | + +You only need tokens for the platforms you use. If you only parse GitLab repos, you don't need a GitHub token, and vice versa. Create tokens with `repo` scope (GitHub) or `read_repository` scope (GitLab) for private repository access. + +## Access Control + +Admin credentials are set during first login (default: `admin` / `admin`). Change these immediately after setup via **Settings > Change Credentials**. + +The Settings page lets you control which operations are available without authentication. + +| Permission | Default | Description | +|---|---|---| +| Allow anonymous parse | Off | Allow unauthenticated users to trigger parsing | +| Allow anonymous refresh | Off | Allow unauthenticated users to refresh libraries | +| Allow anonymous delete | Off | Allow unauthenticated users to delete libraries | +| Allow anonymous support bundle | Off | Allow unauthenticated support bundle downloads | + +When a permission is off, the operation requires admin login. The MCP endpoint and search API are always publicly accessible. + +## Policies + +Policies let you control which public documentation from the Context7 cloud is accessible to your on-premise instance. They do not affect locally parsed on-premise content. + +Access Policies from **Settings > Policies** tab. Requires admin login and a valid `LICENSE_KEY`. + +For details on source type toggles and library filters, see [Customizing What Is Retrieved](/security/data-privacy#customizing-what-is-retrieved). + +## Web UI + +Open your deployment URL in a browser to access the dashboard. From here you can: + +- Add and remove libraries +- Trigger re-indexing +- Monitor parsing status and logs +- Update AI provider settings, git tokens, and permissions +- Configure policies for public cloud documentation access +- Test MCP connectivity +- Change admin credentials + +## Operations + +For updating, health checks, and other operational tasks, see the deployment guide for your platform: + +- [Docker Operations](/enterprise/deployment/docker#operations) +- [Kubernetes Operations](/enterprise/deployment/kubernetes#operations) + +## Support + +For license issues, upgrade requests, or deployment questions, contact [context7@upstash.com](mailto:context7@upstash.com). diff --git a/docs/enterprise/security/entra-sso.mdx b/docs/enterprise/security/entra-sso.mdx new file mode 100644 index 0000000..51eb704 --- /dev/null +++ b/docs/enterprise/security/entra-sso.mdx @@ -0,0 +1,239 @@ +--- +title: "Microsoft Entra ID (SSO)" +sidebarTitle: "Entra SSO" +description: "Let your teamspace sign in with Microsoft Entra ID instead of shared passwords." +--- + +Context7 On-Premise supports single sign-on with Microsoft Entra ID (formerly Azure AD). Once configured, anyone in your Entra tenant who is assigned one of the Context7 app roles can sign in to the dashboard with their work account, and Context7 creates a matching user record automatically on their first login. + +This guide walks through the full setup end-to-end: registering an application in Microsoft Entra, wiring it into Context7, and verifying a user can sign in. Plan for about 10 to 15 minutes for the Entra side and a minute or two on the Context7 side. + +## Before you start + +You'll need: + +- An **Entra admin** (or someone who can register applications in your tenant). +- A running Context7 On-Premise instance that you can reach in your browser. +- The Context7 admin password. This is the same account you use to open **Teamspace Settings** today. On a fresh install it is `admin` / `admin` until you change it. + + +Entra SSO is an **addition** to password login, not a replacement. The seeded admin account keeps working even after you turn on SSO, so you never get locked out if the Entra app goes sideways. + + +## Part 1: Register the application in Microsoft Entra + +### Step 1: Create a new app registration + +In the [Azure portal](https://portal.azure.com), open **Microsoft Entra ID** from the left sidebar. Expand **Manage** and click **App registrations**, then **+ New registration**. + +Fill in the form: + +- **Name**: `Context7` (anything memorable, your users won't see it) +- **Supported account types**: *Accounts in this organizational directory only* +- **Redirect URI**: pick **Web** from the dropdown and enter `https:///api/auth/entra/callback`. For a local test deployment that's usually `http://localhost:3000/api/auth/entra/callback`. + +Click **Register**. + + + ![Azure App registrations: New registration form](/images/enterprise/entra-sso/01-register-app.png) + + + +The redirect URI has to match *exactly* what Context7 sends later: same scheme (`http` vs `https`), same host, same port, same path. Microsoft compares byte-for-byte. + + +### Step 2: Copy the Application (client) ID and Directory (tenant) ID + +After registering, you land on the app's Overview page. Two values matter here: + +- **Application (client) ID** +- **Directory (tenant) ID** + +Copy both somewhere temporary. You'll paste them into Context7 later. + + + ![Azure app Overview showing client and tenant IDs](/images/enterprise/entra-sso/02-app-overview.png) + + + +These aren't secrets. The client ID is public information that's sent in every sign-in request; the tenant ID identifies your Entra directory. It's still good hygiene to treat them like configuration values rather than pasting them into public places. + + +### Step 3: Create a client secret + +From the app's left sidebar, open **Certificates & secrets**, stay on the **Client secrets** tab, then click **+ New client secret**. + +Give it a description (for example, `Context7 on-premise`), pick an expiry (180 days or 12 months are common), and click **Add**. + + + ![Client secrets tab with New client secret form](/images/enterprise/entra-sso/03-client-secret.png) + + + +The **Value** column is only shown once, right after you create the secret. Copy it immediately. If you navigate away before copying, you'll need to create a new secret and start over. + + +Copy the **Value**. This is what Context7 will use to authenticate itself when talking to Microsoft. Put it next to the client and tenant IDs you copied earlier. + +### Step 4: Define the two app roles + +Context7 maps Entra app roles to its own admin/member roles. You'll create one of each in the Entra app. + +From the left sidebar, click **App roles**, then **+ Create app role**. Fill in the first role: + +- **Display name**: `Context7 Admin` +- **Allowed member types**: *Users/Groups* +- **Value**: `Context7.Admin` +- **Description**: anything descriptive, like "Full admin access to the Context7 teamspace" +- Leave *Do you want to enable this app role?* checked. + +Click **Apply**. + +Repeat for the member role: + +- **Display name**: `Context7 Member` +- **Allowed member types**: *Users/Groups* +- **Value**: `Context7.Member` +- **Description**: "Standard member access" + + + ![App roles page showing Context7.Admin and Context7.Member](/images/enterprise/entra-sso/04-app-roles.png) + + + +The **Value** column is what ends up in the sign-in token's `roles` claim. Context7 defaults to looking for `Context7.Admin` and `Context7.Member`, but if your organization has a naming convention (for example, `CTX7_ADMIN`), you can use those values instead. Just remember what you chose so you can enter the same strings in Context7 later. + + +### Step 5: Require assignment and assign users + +By default, any user in your tenant can attempt to sign in to an Entra-registered app. You almost certainly want to restrict that to a known group of people. + +Go back to **Microsoft Entra ID → Enterprise applications** (a *different* section from App registrations, but the same app viewed differently). Find and click your **Context7** app, open **Properties**, set **Assignment required?** to **Yes**, and **Save**. + + + ![Enterprise app Properties page with Assignment required set to Yes](/images/enterprise/entra-sso/05-assignment-required.png) + + +Now open **Users and groups** on the same app and click **+ Add user/group**. For each person you want to grant access: + +1. Pick the user (or a group) under **Users**. +2. Pick a role: **Context7 Admin** for teamspace administrators, **Context7 Member** for everyone else. +3. Click **Assign**. + + + ![Assigning a user and selecting a role](/images/enterprise/entra-sso/06-assign-user-role.png) + + +At a minimum, assign yourself the **Context7 Admin** role so you can test the flow end-to-end. If you're rolling SSO out to a team, assign a second person as a **Context7 Member** for a realistic member-side sanity check. + +## Part 2: Configure Context7 + +### Step 1: Open the Entra SSO card + +Sign in to your Context7 dashboard with the password admin account. Open **Teamspace Settings**, and under **Authentication** you'll find a card titled **Microsoft Entra SSO**. + + + ![Context7 Teamspace Settings with the Microsoft Entra SSO card highlighted](/images/enterprise/entra-sso/07-context7-settings-card.png) + + +### Step 2: Fill in the credentials + +Paste the three values you copied from Azure into the form: + +- **Tenant ID** → the Directory (tenant) ID from the Azure Overview page +- **Client ID** → the Application (client) ID from the same page +- **Client Secret** → the secret *Value* from the Certificates & secrets page + +If your organization uses different role names from the defaults, update **Admin role value** and **Member role value** to match the strings you entered as **Value** when creating the app roles in Azure. + + +The **Callback URL** shown at the bottom of the card is exactly what Context7 will send to Microsoft during sign-in. If it doesn't match the redirect URI you registered in Step 1 of Part 1, go back to Azure → App registrations → Context7 → Authentication and fix it there. The copy button next to the URL makes it easy to paste into the Azure form verbatim. + + +### Step 3: Test the connection + +Before turning SSO on for your users, click **Test connection**. Context7 will make a server-to-server request to Microsoft using the credentials you entered. You'll see one of three results: + +- **Green banner**: credentials are valid. You're ready to flip the toggle on. +- **"Tenant ID is invalid"**: the Tenant ID doesn't match an Entra directory. Double-check you haven't pasted the Client ID into the Tenant field (an easy mistake, since both are GUIDs). +- **"Client ID was not found in this tenant"** or **"Client secret is invalid"**: recheck the values against the Azure Overview and Certificates & secrets pages. If the secret expired, generate a new one in Azure and paste the new value. + +### Step 4: Enable SSO + +Once the test passes, click the toggle at the top-right of the card, then **Save Microsoft Entra Settings** at the bottom. The status indicator should read **Configured · Sign-in button visible on /login**. + + + ![Entra SSO card with values filled, connection verified, and toggle on](/images/enterprise/entra-sso/08-filled-credentials.png) + + +## Part 3: Sign in + +Open `/login` in a new browser tab. Incognito is handy here because it guarantees you aren't reusing your existing admin session. You should see a **Continue with Microsoft Entra ID** button above the username/password form. + + + ![Login page showing Continue with Microsoft Entra ID button](/images/enterprise/entra-sso/10-login-page.png) + + +Click it. Microsoft handles the authentication. You may need to pick an account, consent to the app on first sign-in, or complete MFA depending on your tenant's policies. On success you're bounced back to Context7, a session cookie is set, and you're signed in. + +The first time each person signs in, Context7 creates a user record with the display name, email, and role sourced from their Entra account. On subsequent sign-ins, the existing record is updated with any changes to those fields (for example, if you reassign them from Member to Admin in Entra, the promotion takes effect on their next sign-in). + +## Managing roles after setup + +Role assignments live entirely in Entra. To change someone's access in Context7: + +- **Promote a member to admin**: in Entra, go to Enterprise applications → Context7 → Users and groups, remove their Member role, add the Admin role, and ask them to sign out and back in. +- **Revoke access**: remove the user from Users and groups in Entra. Existing browser sessions remain valid until they expire or sign out. If you need to cut them off immediately, restart Context7 (in-memory sessions are cleared on restart) or have an admin explicitly delete their user row from the teamspace. +- **Audit who signed in recently**: **Teamspace Settings → Users** shows every Context7 user with their auth provider and last-login timestamp. + + + ![Teamspace Users tab showing password and Entra users side by side](/images/enterprise/entra-sso/11-users-tab.png) + + +## Troubleshooting + +### `AADSTS50011: redirect URI mismatch` + +The redirect URI Context7 sent doesn't match any redirect URI registered on the Azure app. Open the app in Azure → **Authentication** and compare the list against the **Callback URL** shown on the Context7 SSO card. Check especially: + +- `http://` vs `https://` must match exactly. +- Port number: if you're running Context7 on a non-standard port, the Entra registration needs the same port. +- Path: must be `/api/auth/entra/callback` with no trailing characters. + +If you're running behind a reverse proxy, make sure it forwards the `Host` header unchanged; otherwise Context7 will build a callback URL for the internal host, not the public one your users see. + +### "This Microsoft Entra account is not assigned a supported Context7 app role" + +The user completed Microsoft sign-in but doesn't have either the Admin or Member app role assigned. Open Enterprise applications → Context7 → Users and groups, and verify they're listed with a role. If they are, confirm the role **Value** in the app registration matches the **Admin role value** / **Member role value** you entered in Context7 (they're case-sensitive). + +### "Microsoft sign-in session expired" + +This means the short-lived cookie Context7 uses to track the in-flight sign-in request was dropped or didn't come back. Most common causes: + +- The user started sign-in on one host (for example `localhost:3000`) and came back on a different one (`localhost:5173`). Stick to one host for the whole flow. +- A browser extension or strict privacy setting is blocking cookies. + +Have them retry in a clean browser window. + +### The Entra button doesn't appear on `/login` + +The card's status indicator tells you why: + +- **Not configured**: tenant ID, client ID, or client secret is missing. Fill them in and save. +- **Configured · Toggle on to show the sign-in button**: credentials are saved but the feature is off. Flip the toggle at the top of the card. + +### Client secret expired + +Entra rejects the test with `"Client secret has expired"` once the secret passes its expiry date. In Azure → Certificates & secrets, create a new secret and paste the new **Value** into the Context7 card. Then click **Test connection** to verify, and **Save**. + +## What this does *not* cover + +A few things that are out of scope for SSO itself but often come up when rolling it out: + +- **Personal MCP API keys**. Once a user signs in via Entra, they can create their own MCP API keys from **Personal Settings → API Keys**. Those are separate from SSO and covered in the main On-Premise guide. +- **Group-based role mapping**. Context7 reads app roles, not group membership. If your team assigns access via Entra security groups, add the group to Users and groups with one of the two Context7 roles. +- **SCIM provisioning**. Users are created lazily on first sign-in. There's no background sync pulling the whole directory. + +For help with Entra-side policies, conditional access, or MFA, work with your Entra admin. Those are tenant-wide concerns and Context7 respects whatever Microsoft returns at the end of the sign-in. + +If you run into something not covered above, contact [context7@upstash.com](mailto:context7@upstash.com) with the **Request Id** from any Microsoft error page and a screenshot of the Context7 SSO card's status indicator. diff --git a/docs/enterprise/security/oidc-sso.mdx b/docs/enterprise/security/oidc-sso.mdx new file mode 100644 index 0000000..b5c9b72 --- /dev/null +++ b/docs/enterprise/security/oidc-sso.mdx @@ -0,0 +1,172 @@ +--- +title: "OpenID Connect (OIDC) SSO" +sidebarTitle: "OIDC SSO" +description: "Let your team sign in with any OIDC-compatible identity provider instead of shared passwords." +--- + +Context7 On-Premise supports single sign-on with any provider that implements the OpenID Connect standard: Okta, Keycloak, Auth0, Ping Identity, on-premise LDAP-backed IdPs, and many others. Once you connect your provider, team members are redirected to your identity provider to authenticate, and Context7 creates or updates their user record automatically on each sign-in. + +The login flow uses the Authorization Code flow with PKCE, so no tokens are ever passed through the browser query string and no client secret is exposed to the frontend. + +## Before you start + +You will need: + +- Admin access to your identity provider so you can register a new application. +- A running Context7 On-Premise instance that you can reach in your browser. +- The Context7 admin password. On a fresh install it is `admin` / `admin` until you change it. + + +Only one SSO provider can be active at a time. If you already have Microsoft Entra ID configured, enabling OIDC will automatically disable Entra, and vice versa. + + +## Part 1: Register Context7 in your identity provider + +The exact steps depend on your provider, but the end result is the same in every case: you need a **client ID**, a **client secret**, and your provider's **issuer URL**. + +### What to configure in your IdP + +Create a new application or client in your identity provider and set the following: + +- **Application type**: Confidential (server-side) web application. +- **Allowed grant type**: Authorization Code. +- **Redirect URI / Callback URL**: `https:///api/auth/oidc/callback`. The exact URL is shown in the Context7 settings card once you open it, and there is a copy button next to it. + +If your provider supports PKCE (most modern ones do), leave it enabled. Context7 always sends a PKCE `code_challenge` regardless of whether the provider requires it. + +### Group claims (for role mapping) + +Context7 maps a group claim in the token to admin or member roles. Most providers let you include group membership in the ID token or expose it from the UserInfo endpoint. Either location works; Context7 checks both. + +In your IdP, configure the application to include the user's groups in the token. The default claim name Context7 looks for is `groups`. Common provider-specific steps: + +- **Okta**: add a Groups claim to the authorization server with a filter matching the groups you want to expose. +- **Keycloak**: enable the `groups` scope or add a Group Membership mapper to the client. +- **Auth0**: add a custom claim action that sets `groups` from the user's app metadata or roles. + +If your provider uses a different claim name, you can change what Context7 looks for in the **Groups claim** field in the settings card. + +## Part 2: Configure Context7 + + + + Sign in to your Context7 dashboard with the admin account. Open **Teamspace Settings**, scroll to the **Authentication** section, and click the **Single Sign-On** card. Select the **OIDC** tab. + + + ![Context7 Settings showing the Single Sign-On card with the OIDC tab selected](/images/enterprise/oidc-sso/02-sso-card-oidc.png) + + + + + Toggle **Enable OIDC** on, then fill in the fields: + + - **Button label**: the text shown on the sign-in button on the login page. Something like your company name or "Sign in with Acme" works well. + - **Issuer URL**: your provider's base URL. Context7 appends `/.well-known/openid-configuration` to discover endpoints automatically. For Okta this looks like `https://your-org.okta.com`, for Keycloak it is `https://keycloak.example.com/realms/your-realm`. + - **Client ID**: the client or application ID from your IdP registration. + - **Client Secret**: the secret generated by your IdP. Context7 stores this encrypted and never returns it to the browser after saving. + - **Scopes**: space-separated scopes to request. The default `openid profile email` works for most setups. Add `groups` or any custom scope your IdP requires to include group membership. + + The **Callback URL** at the bottom of the form is what you registered as the redirect URI in your IdP. If you need to update it, copy it with the button and paste it into your IdP's application settings. + + + + The **Group mapping** section controls which users get which role in Context7. + + + ![OIDC configuration card showing the Group mapping section](/images/enterprise/oidc-sso/03-group-mapping.png) + + + - **Groups claim**: the name of the claim in the token that contains the user's groups. Default is `groups`. + - **Admin group value**: the exact group name that maps to the Context7 admin role. Admins can open Teamspace Settings and manage other users. + - **Member group value**: the exact group name that maps to the member role. Members can use the workspace but cannot access settings. + + If you leave both group values blank, every authenticated user gets the member role automatically. This is useful when your IdP does not emit a groups claim and you want to allow any user from your organization in. + + + + Click **Test connection** before saving. Context7 fetches your provider's discovery document and confirms the required endpoints are present and reachable. A green banner means everything looks good. A red error usually means the issuer URL is wrong or the provider is not accessible from the Context7 server. + + + + Click **Save & Apply**. The status pill in the card header will change to **Live**. + + + +## Part 3: Sign in + +Open `/login` in a new browser window. You will see a **Continue with [your button label]** button at the top of the sign-in card. + + + ![Login page showing the SSO button and the optional password form below](/images/enterprise/oidc-sso/01-login-page.png) + + +Click it. You are redirected to your identity provider's login page. After authenticating there, your provider sends you back to Context7 with an authorization code. Context7 exchanges the code for tokens, validates the ID token signature and claims, and either creates a new user or updates the existing one. + +The first time someone signs in, Context7 creates a user record using their name, email, and role from the token claims. On subsequent sign-ins, the name, email, and role are refreshed from the latest token, so changes in your IdP take effect automatically on the next login. + +## Disabling password sign-in + +Once OIDC is live, you can turn off password-based sign-in entirely so that all users must authenticate through your IdP. + +Open the **Password sign-in** card directly below the SSO card and toggle it off. + + + ![Password sign-in card with the toggle in the Enabled state](/images/enterprise/oidc-sso/04-password-card.png) + + + +Disabling password sign-in means the default admin account and any manually created password users will no longer be able to sign in via the login form. Make sure at least one admin is mapped through OIDC before turning it off, so you do not lock yourself out. If you turn SSO off later, Context7 will automatically re-enable password sign-in as a safety measure. + + +## Managing users + +All users who have signed in appear in **Teamspace Settings → Users**, along with their authentication provider and last login time. + + + ![Teamspace Settings Users tab showing OIDC-provisioned users](/images/enterprise/oidc-sso/05-users-tab.png) + + +Roles are controlled by group membership in your IdP. To change someone's role, update their group assignment in your identity provider. The change takes effect on their next sign-in. + +To revoke access, remove the user from the relevant group in your IdP. Existing browser sessions remain valid until they expire naturally or the user signs out. If you need to cut access immediately, an admin can delete the user row from the Users tab in Teamspace Settings. + +## Troubleshooting + +### "OIDC SSO is not configured" + +The toggle is on but some required fields are missing or the config was not saved. Open the OIDC tab in the SSO card and check that Issuer URL, Client ID, and Client Secret are all filled in, then click **Save & Apply**. + +### Test connection fails + +The most common reasons are: + +- **Wrong issuer URL**: double-check it does not include a trailing slash and points to your realm root. For Keycloak, the format is `https://host/realms/realm-name`, not `https://host/auth/realms/realm-name` (the `/auth` prefix was removed in Keycloak 17). +- **Network access**: the Context7 server must be able to reach your IdP's HTTPS endpoint. If you are running air-gapped or on an internal network, confirm there is no firewall blocking outbound requests to your IdP from the server. + +### "This account is not assigned a supported Context7 group" + +The user authenticated successfully but their token did not contain either of the configured group values. Check that: + +1. The groups claim is included in the token from your IdP (use your IdP's token preview or decode the returned JWT at jwt.io). +2. The **Groups claim** field in Context7 matches the claim name exactly (case-sensitive). +3. The **Admin group value** or **Member group value** matches the group name exactly, including casing and spacing. + +### "Single sign-on session expired. Please try again." + +The short-lived cookie that tracks the in-progress sign-in was lost between the redirect to the IdP and the return. The most common causes are: + +- Starting the flow on one hostname and returning on a different one (for example, `localhost:3000` vs `localhost:5173`). +- A browser or proxy stripping the session cookie. +- Taking longer than 10 minutes to complete the IdP login, which is when the cookie expires. + +Having the user retry in a clean browser window usually resolves it. + +### Redirect URI mismatch + +If your IdP returns a redirect URI error, the callback URL you registered in the IdP does not exactly match what Context7 sends. Copy the **Callback URL** from the Context7 settings card using the copy button and paste it verbatim into your IdP's allowed redirect URIs. Pay attention to `http` vs `https` and the port number. + +If Context7 is behind a reverse proxy, make sure the proxy forwards the `Host` and `X-Forwarded-Proto` headers correctly so Context7 can build the right callback URL. + +--- + +For anything not covered here, contact [context7@upstash.com](mailto:context7@upstash.com). diff --git a/docs/howto/api-keys.mdx b/docs/howto/api-keys.mdx new file mode 100644 index 0000000..450a075 --- /dev/null +++ b/docs/howto/api-keys.mdx @@ -0,0 +1,50 @@ +--- +title: Manage API Keys +description: Create and manage API keys for Context7 authentication +--- + +API keys authenticate your requests to Context7's documentation services. + +## Managing API Keys + +![API Keys card showing list of keys with details](/images/dashboard/api-keys-card.png) + +### Creating API Keys + + + + Click **Create API Key** in the API Keys card. + + + Enter a name (optional but recommended). Descriptive names like "Cursor", "Claude", "VS Code", or "Devin Desktop" help you identify the key later. + + + Keys are shown only once for security. The format is `ctx7sk-**********************`. + + + Use it in your requests or MCP configuration: + + ```bash + curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=routing" \ + -H "Authorization: Bearer YOUR_API_KEY" + ``` + + + +Store your API key securely. You won't be able to see it again after creation. + +### Revoking Keys + + + + Click the delete button next to the key you no longer need. + + + Confirm in the modal. The key deactivates immediately — all requests using it will fail. + + + + + Revoking a key is permanent and cannot be undone. Update any applications using the key before + revoking. + diff --git a/docs/howto/chat-widget.mdx b/docs/howto/chat-widget.mdx new file mode 100644 index 0000000..4f4bbcc --- /dev/null +++ b/docs/howto/chat-widget.mdx @@ -0,0 +1,211 @@ +--- +title: Add the Chat Widget +description: Embed an AI-powered chat assistant on your documentation site +--- + +Add an AI chat widget to your documentation site so visitors can ask questions and get instant answers powered by your library's documentation on Context7. + +The widget is a lightweight JavaScript snippet that renders a floating chat button. When clicked, it opens a chat panel where users can ask questions about your library and receive AI-generated answers grounded in your documentation. + +The chat widget is available to library owners who have [claimed their library](/howto/claiming-libraries). + +![Chat widget panel showing AI-powered documentation assistant](/images/dashboard/chat-widget.png) + +## How It Works + +1. A visitor clicks the chat bubble on your site +2. They type a question about your library +3. The widget searches your library's documentation on Context7 +4. An AI model generates an answer using the relevant documentation +5. The response streams back in real time with markdown formatting + +## Setup + + + + You must be a verified owner of the library on Context7. If you haven't claimed it yet, follow the [Claim Your Library](/howto/claiming-libraries) guide. + + + + Navigate to your library's admin page: + + ``` + https://context7.com/{owner}/{repo}/admin + ``` + + Open the **Chat** tab and toggle **Widget enabled** on. + + + + Add the domains where the widget will be embedded. The widget will only work on domains you explicitly allow. + + Examples: + - `docs.example.com` — exact domain match + - `*.example.com` — matches all subdomains (e.g., `docs.example.com`, `blog.example.com`) + - `example.com` — matches the root domain only + + + The widget will not work on any external site until you add at least one allowed domain. + + + + + Click **Save** to persist your widget configuration. + + + + Copy the embed code from the admin panel and add it to your site's HTML: + + ```html + + ``` + + Place this tag in your root layout or HTML file so the widget loads on every page. The script loads asynchronously and does not block page rendering. + + + +## Adding with AI + +You can use an AI coding assistant to add the widget automatically. Copy the following prompt and paste it into Claude Code, Cursor, or any AI coding assistant. Replace `/owner/repo` with your library ID. The assistant will detect your framework and place the script tag in the correct location. + +``` +Add the Context7 chat widget to my documentation site. This is a lightweight +JavaScript widget that adds an AI-powered chat assistant to any webpage. It +loads asynchronously and renders a floating chat button. + +The widget is loaded via a script tag: + + +Detect which framework this project uses and add the widget accordingly. Place +it in the root layout or HTML file so it loads on every page. + +Optional attributes: data-color (hex color, default #059669), data-position +(bottom-right or bottom-left), data-placeholder (input placeholder text), +data-welcome-message (initial assistant message shown when the chat opens). +``` + +## Framework Examples + + + + Use the `next/script` component in your root layout so the widget loads on every page: + + ```tsx app/layout.tsx + import Script from "next/script"; + + export default function RootLayout({ children }) { + return ( + + + {children} + +``` + +**Custom placeholder text:** + +```html + +``` + +**Custom welcome message:** + +```html + +``` + +### Position Options + +| Value | Description | +| -------------- | --------------------------------- | +| `bottom-right` | Fixed to the bottom-right corner | +| `bottom-left` | Fixed to the bottom-left corner | + +## Domain Configuration + +### Allowed Domains + +You can configure up to **20 allowed domains** per library. The widget validates the requesting origin against this list on every chat request. + +| Pattern | Matches | +| ------------------ | --------------------------------------------------- | +| `docs.example.com` | Only `docs.example.com` | +| `*.example.com` | Any subdomain: `docs.example.com`, `blog.example.com`, and `example.com` itself | +| `example.com` | Only the root domain `example.com` | + + + Domain validation is enforced server-side. Requests from domains not in your allowed list are rejected with a 403 error. + + +### Adding and Removing Domains + +Manage domains from the **Chat** tab on your library's admin page: + +1. Click **Add domain** to add a new entry +2. Enter the domain (e.g., `docs.example.com` or `*.example.com`) +3. Click **Save** to apply changes + +To remove a domain, click the trash icon next to it and save. diff --git a/docs/howto/claiming-libraries.mdx b/docs/howto/claiming-libraries.mdx new file mode 100644 index 0000000..33bd5bf --- /dev/null +++ b/docs/howto/claiming-libraries.mdx @@ -0,0 +1,289 @@ +--- +title: Claim Your Library +description: Verify ownership and manage your library's configuration via the admin panel +--- + +As a library owner, you can claim your library on Context7 to unlock advanced configuration options through a web-based admin panel. This gives you full control over how your documentation is parsed and presented to developers. + +Library claiming is available for Git repositories, websites, and llms.txt sources. + +## Why Claim Your Library? + +Claiming ownership provides several benefits: + +- **Web-based configuration**: Edit settings through a user-friendly interface instead of committing changes +- **Teamspace management**: All project members can manage the library configuration +- **Version management**: Add and manage multiple versions of your library documentation +- **Usage analytics**: View metrics on how developers use your library's documentation +- **Higher refresh limits**: Get higher rate limits for refresh operations to better manage your content +- **Apply for verification**: Only owners can apply for the verified badge. [Learn more about verification](/howto/verification) + +## Claiming Process + + + + You can access the admin page in two ways: + + **From the Dashboard:** + Find your library in the dashboard and click the "Manage" button to open the admin configuration page. + + + Manage button on library card + + + **Via Direct URL:** + Go directly to your library's admin page at: + + ``` + https://context7.com/{owner}/{repo}/admin + ``` + + For example: `https://context7.com/vercel/next.js/admin` + + + + + If you haven't claimed the library yet, you'll see a "Claim Library" button in the header. Click it to open the claiming modal. + + + Claim Library button + + + + + + In the claiming modal, you'll see a generated `context7.json` configuration with your unique public key: + + + Claim library modal + + + The modal provides a JSON snippet like this: + + ```json + { + "url": "https://context7.com/vercel/next.js", + "public_key": "pk_abc123xyz..." + } + ``` + + Click "Copy" to copy the configuration to your clipboard. + + + + + + + Create a `context7.json` file in the **root** of your repository with the copied content: + + ```json + { + "url": "https://context7.com/vercel/next.js", + "public_key": "pk_abc123xyz..." + } + ``` + + + The `url` must exactly match your library's URL on Context7, and the `public_key` must match the key shown in the modal. + + + Commit and push the file to your repository's default branch. + + + Host the `context7.json` file anywhere under your library's base URL so it is publicly reachable. For example: + + ``` + https://docs.example.com/mylib/context7.json + ``` + + The file must contain the copied content: + + ```json + { + "url": "https://context7.com/websites/mylib", + "public_key": "pk_abc123xyz..." + } + ``` + + + The `url` must exactly match your library's URL on Context7, and the `public_key` must match the key shown in the modal. + + + Once the file is live, paste the full URL to your hosted `context7.json` into the input field shown in the modal. + + + + + + Click "Claim Library". Context7 will fetch your `context7.json`, verify the URL and public key, and grant you access to the admin panel. + + + +## Admin Panel Overview + +After claiming your library, the admin page shows a full configuration editor with five main tabs: + +- **Configuration**: Edit all library settings +- **Chat**: Embed an AI chat assistant on your documentation site +- **Benchmark**: Evaluation of the quality of your library's documentation +- **Metrics**: View usage statistics +- **Versions**: Manage different versions and tags of your library + +## Configuration Fields + +### Basic Information + +These fields are available for all library types. + +| Field | Description | Limits | +| ----------------- | --------------------------------------------------------------------------------------------------------- | ------------------ | +| **Project Title** | Display name for your library in Context7. Used when the LLM cannot generate a name with high confidence. | Max 100 characters | +| **Description** | Brief description of your library's purpose. | Max 500 characters | + +### Source Settings + + + + | Field | Description | Limits | + | ---------------------- | ----------------------------------------------------------------------------------------- | ------------------------------- | + | **Branch** | Git branch to parse. Leave empty for default branch. | Max 100 characters | + | **Folders to Include** | Specific folder paths to include when parsing. Leave empty to scan the entire repository. | Max 50 folders, 255 chars each | + | **Folders to Exclude** | Folder paths or patterns to exclude from parsing. Supports glob patterns. | Max 50 patterns, 255 chars each | + | **Files to Exclude** | Specific file names to exclude (filename only, not full path). | Max 100 files, 255 chars each | + + #### Exclusion Pattern Examples + + The exclusion fields support various pattern types: + + ``` + node_modules → Excludes any folder named "node_modules" anywhere + ./build → Excludes "build" only at repository root + **/dist → Excludes any "dist" folder anywhere (globstar) + docs/**/internal → Excludes "internal" folders under docs + *.test → Excludes folders ending with .test + ``` + + + `excludeFiles` only accepts filenames, not paths. Use `CHANGELOG.md` instead of + `docs/CHANGELOG.md`. + + + + | Field | Description | Limits | + | ---------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------- | + | **Base URL** | The root URL to crawl for documentation. | Max 100 characters | + | **Display URL** | Optional URL shown to users instead of the base URL. | Max 500 characters | + | **Keep Hash (URL Fragments)**| Whether to treat URLs with different hash fragments as distinct pages. Disabled by default. | Boolean | + | **Keep Query Parameters** | Whether to treat URLs with different query strings as distinct pages. Enabled by default. | Boolean | + | **Exclude URLs** | URL patterns to exclude from crawling. Supports wildcards. | Max 100 patterns | + + + +### AI Instructions + +| Field | Description | Limits | +| ---------------- | ------------------------------------------------------------------------------- | ---------------------------- | +| **Custom Rules** | Best practices and guidelines for AI coding assistants when using your library. | Max 50 rules, 255 chars each | + +Example rules: + +- "Always use TypeScript for better type safety" +- "Import components from the main package, not internal paths" +- "Use environment variables for API keys, never hardcode them" + +### Advanced Settings + +Available for Git repositories and websites. + +| Field | Description | Limits | +| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| **Skip Automatic Version Detection** | By default, outdated library versions are automatically detected and excluded from indexing. Enable to include all versions regardless of age. | Boolean | +| **Redirect URL** | Redirect users to a different library. Leave empty to disable. | Max 500 characters | +| **Disallow Indexing** | Opt-out from Context7. When enabled, documentation content is removed and the library becomes inaccessible. | Boolean | + +## Managing Versions + +The Versions tab lets you configure previous versions of your library that should be available in Context7. + + + Versions tab + + +You can add versions using either: + +- **Git tags**: Reference a specific release tag (e.g., `v1.2.0`) +- **Git branches**: Reference a branch for version-specific documentation (e.g., `release-1.x`) + +| Limit | Value | +| ---------------- | ----------------- | +| Maximum versions | 20 | +| Tag/branch name | Max 50 characters | + +## Library Metrics + +The Metrics tab provides insights into how developers are using your library through Context7. + + + Metrics tab + + +### Usage Statistics + +At the top of the metrics page, you'll see key usage numbers: + +| Metric | Description | +| ---------------------- | --------------------------------------------------------------------- | +| **Page Views** | Number of times your library page was viewed on Context7 | +| **API Requests (TXT)** | Documentation requests via the REST API | +| **MCP Requests** | Documentation requests via the MCP server (from AI coding assistants) | + +The metrics page also includes a usage chart showing trends over time, topic queries showing what developers ask about, and country distribution of requests. + +All team members can view library settings; owners and admins can edit them. See [Teamspace Management](/howto/teamspace) for role details. + +## Removing Ownership + + + + Navigate to your library's admin page at `https://context7.com/{owner}/{repo}/admin`. + + Click the ownership menu in the header area. + Select "Remove Ownership" and confirm the action. + + + + Removing ownership keeps the admin configuration intact. Another user can claim the library and + inherit the existing settings. + + +## Troubleshooting + +### "context7.json not found" + +Ensure the file is: + +- Named exactly `context7.json` (lowercase) +- Located in the repository root, not a subdirectory +- Committed and pushed to the default branch + +### "URL mismatch" + +The `url` field in your `context7.json` must exactly match: + +``` +https://context7.com/{owner}/{repo} +``` + +Check for typos, case sensitivity, and trailing slashes. + +### "Public key mismatch" + +The `public_key` in your file must match the key shown in the claiming modal. Copy the entire key including the `pk_` prefix. + +### Changes not appearing + +After saving configuration changes, you may need to: + +- Manually trigger a refresh from the library page +- Clear any cached documentation on your end + diff --git a/docs/howto/oauth.mdx b/docs/howto/oauth.mdx new file mode 100644 index 0000000..1fa6ce5 --- /dev/null +++ b/docs/howto/oauth.mdx @@ -0,0 +1,43 @@ +--- +title: Set Up OAuth +description: Authenticate with Context7 MCP server using OAuth 2.0 +--- + + + OAuth is only available for remote HTTP connections. For local MCP connections using stdio + transport, use [API key authentication](/howto/api-keys) instead. + + +Context7 MCP server supports OAuth 2.0 authentication for MCP clients that implement the [MCP OAuth specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). + +## Why Use OAuth? + +| Feature | OAuth | API Keys | +| -------------------------- | ----- | -------- | +| No manual key management | ✅ | ❌ | +| Automatic token refresh | ✅ | ❌ | +| Works with stdio transport | ❌ | ✅ | + +## Configuration + +To use OAuth, change the endpoint from `/mcp` to `/mcp/oauth` in your client configuration: + +```diff +- "url": "https://mcp.context7.com/mcp" ++ "url": "https://mcp.context7.com/mcp/oauth" +``` + +## How It Works + +1. Your MCP client connects to the OAuth endpoint +2. You're redirected to Context7 to sign in +3. After signing in, you're redirected back to your client +4. Your client automatically handles token refresh + + +**Authentication required after setup.** Most clients won't authenticate automatically. After adding the OAuth endpoint, you'll need to explicitly authenticate through your client's MCP settings. For example, in Claude Code run `/mcp`, select the server, and choose "Authenticate". + + +## Client Support + +OAuth authentication requires your MCP client to support the [MCP OAuth specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). If your client doesn't support OAuth, use [API key authentication](/howto/api-keys) instead. diff --git a/docs/howto/policies.mdx b/docs/howto/policies.mdx new file mode 100644 index 0000000..6daf4ec --- /dev/null +++ b/docs/howto/policies.mdx @@ -0,0 +1,62 @@ +--- +title: Manage Policies +description: Control which sources and libraries your teamspace can access +--- + +Policies let you control exactly which documentation your teamspace can pull from Context7. Configure them from the [policies tab](https://context7.com/dashboard?tab=policies) of your dashboard, or programmatically through the [Policies API](/api-reference/policies/get-teamspace-policies). + +Every search and MCP request made with one of the teamspace's API keys is filtered through these policies, so they apply to all members at once. + +Policies are scoped to a teamspace. Only owners and admins can change them; developers have read-only access. + +## Source Type Access + +The **Source Type Access** card toggles entire categories of sources on or off. Disabling a type removes all of its content from results for the whole teamspace. + +| Group | Source Type | What it covers | +| ----------------- | ------------------ | --------------------------------------- | +| Public Sources | Public Repositories | Public GitHub repositories | +| Public Sources | Websites | Indexed documentation websites | +| Public Sources | LLMs.txt | `llms.txt` sources | +| Connected Sources | Confluence | Atlassian Confluence workspace pages | +| Connected Sources | Uploaded Files | Uploaded OpenAPI specs and PDFs | +| Connected Sources | Notion | Connected Notion pages | +| Connected Sources | Private Sources | Privately parsed repositories | + +## Library Filters + +The **Library Filters** card decides which public libraries are accessible. Choose one of two modes: + +### Filter by Quality + +Allow any public library that clears the quality bar you set. Available filters: + +| Filter | Options | +| ----------------- | ------------------------------------ | +| Verification | All · Verified Only | +| Trust score | All · Medium (4+) · High (7+) | +| Freshness | All · 30 days · 90 days · 1 year | +| Repo stars | All · 100+ · 1,000+ · 10,000+ | +| Website backlinks | All · 500+ · 2,500+ · 5,000+ | +| Referring domains | All · 100+ · 500+ · 1,000+ | +| Organic traffic | All · 100+ · 1,000+ · 10,000+ | + +You can also maintain two override lists in quality mode: + +- **Blocked libraries** — always excluded, even if they pass every filter. +- **Excepted libraries** — always allowed, even if they fail the filters. + +### Select Manually + +Ignore the quality bar entirely and grant access only to a hand-picked list of libraries. Anything not on the list is inaccessible. + +The card shows the number of libraries currently accessible under your settings, so you can see the impact before saving. + +## Managing Policies via API + +The same configuration is available over the REST API using a teamspace API key: + +- [Get Policies](/api-reference/policies/get-teamspace-policies) — `GET /api/v2/policies` returns the current configuration and accessible library count. +- [Update Policies](/api-reference/policies/update-teamspace-policies) — `PATCH /api/v2/policies` applies an incremental update; only the fields you include are changed. + +See the [API Guide](/api-guide) for request and response details. diff --git a/docs/howto/private-sources.mdx b/docs/howto/private-sources.mdx new file mode 100644 index 0000000..ba6f89a --- /dev/null +++ b/docs/howto/private-sources.mdx @@ -0,0 +1,97 @@ +--- +title: Add Private Sources +description: Add and manage private source documentation +--- + +Add private sources to Context7 to make your internal documentation available to AI coding assistants. You can add sources from GitHub, GitLab, Bitbucket, other Git providers, Confluence, and OpenAPI specifications. + +![Private Sources card showing a table of added sources and source type options](/images/dashboard/private-sources-card.png) + +## Adding Private Sources + + + + Go to your teamspace's **Sources** tab. + + + Click **Add another** to open the source type selector. + + + - **GitHub** — connect your GitHub account and select a repository + - **GitLab** — connect your GitLab account and select a project + - **Bitbucket** — connect your Bitbucket account and select a repository + - **Other Git** — add any Git repository by URL + - **Confluence** — connect your Confluence workspace + - **OpenAPI** — add an OpenAPI specification + + + Authorize Context7 to access your source (if required). + + + For repositories with little or no written documentation, check **Generate docs** to have Context7 generate documentation from the source code. Also available as the `generateDocs` flag in the [API](/api-guide). + + + Submit the source for parsing. + + + +You must have a Pro or Enterprise plan to add private sources. Public sources can be added from the [Add Library](https://context7.com/add-library) page. + +## Source Management + +### Refreshing Documentation + +Keep your private documentation up to date: + +1. **Click the refresh icon** next to the source +2. Context7 re-parses the source +3. **You're only charged for changed content** — cached pages are free + +**When to refresh**: + +- After major documentation updates +- After releasing new features +- When you notice outdated information + +Refresh private sources only after significant documentation changes to minimize costs. + +### Removing Sources + + + + Click the trash icon next to the source. + + + Confirm in the modal. The source documentation becomes unavailable immediately. + + + + + This action is permanent. The source will no longer be accessible via the API. + + +## Permissions + +Access to private source management is restricted by role. Only Owners and Admins can add, refresh, or remove private sources. Developers can view source documentation but cannot manage sources. + +See [Teamspace Management](/howto/teamspace#roles) for the complete permissions table. + +## Configuration + +### Using `context7.json` + +Add a `context7.json` file to your repository root for better control over parsing: + +```json +{ + "$schema": "https://context7.com/schema/context7.json", + "projectTitle": "Your Project Name", + "description": "Brief description of your project", + "folders": ["docs", "guides"], + "excludeFolders": ["tests", "dist", "node_modules"], + "excludeFiles": ["CHANGELOG.md"], + "rules": ["Always validate user input", "Use TypeScript strict mode"] +} +``` + +See the [Library Owners](/library-owners) page for complete configuration options. diff --git a/docs/howto/rules.mdx b/docs/howto/rules.mdx new file mode 100644 index 0000000..e8d360d --- /dev/null +++ b/docs/howto/rules.mdx @@ -0,0 +1,42 @@ +--- +title: Manage Rules +description: Prepend custom guidelines to the documentation your teamspace retrieves +--- + +Rules are custom instructions that are automatically prepended to the documentation context whenever your teamspace retrieves library docs. Use them to set coding standards, define architectural patterns, or specify framework preferences so every result follows your team's conventions. + +Manage them from the [rules tab](https://context7.com/dashboard?tab=rules) of your dashboard. + +Teamspace Rules are a Pro and Enterprise feature. Only owners and admins can add, edit, or delete rules; developers have read-only access. + +## Rule Scopes + +Each rule applies at one of two scopes: + +- **Global Rules** — apply to every library your teamspace accesses. +- **Library-Specific Rules** — apply only when retrieving docs for a particular library. + +## Examples + +- "Always use TypeScript strict mode" +- "Prefer server components in Next.js" +- "Use the App Router, not the Pages Router" + +## Adding a Rule + + + + Open the [rules tab](https://context7.com/dashboard?tab=rules) and click **Add Rule...**. + + + Pick **Global** or a specific **Library**. + + + Write the instruction you want prepended to retrieved documentation. + + + Save the rule. It takes effect on the next documentation request made with the teamspace's API keys. + + + +Existing rules are grouped by scope in the list. Select **Global Rules** or any library entry to edit or remove its rules. diff --git a/docs/howto/teamspace.mdx b/docs/howto/teamspace.mdx new file mode 100644 index 0000000..a88abee --- /dev/null +++ b/docs/howto/teamspace.mdx @@ -0,0 +1,67 @@ +--- +title: Manage Your Teamspace +description: Invite members and manage teamspace permissions +--- + +Add team members, assign roles, and manage access to your Context7 dashboard from the [members tab](https://context7.com/dashboard?tab=members). + +![Members tab displaying team members list with owner, admins, and developers](/images/dashboard/members-tab.png) + +## Creating a Teamspace + +![Create teamspace dropdown](/images/dashboard/user-dropdown.png) + + + + Click **Create a teamspace** from the top-left dropdown. + + + Enter a teamspace name. + + + +You must have a Pro or Enterprise plan to create a teamspace. Only the teamspace owner needs a paid plan — invited members don't need their own subscription. Once added, all members automatically benefit from the team's Pro or Enterprise limits. + +## Roles + +| Permission | Owner | Admin | Developer | +| --------------------- | ----- | ----- | --------- | +| View dashboard | ✓ | ✓ | ✓ | +| Create API keys | ✓ | ✓ | ✓ | +| Manage team members | ✓ | ✓ | ✗ | +| Manage library access | ✓ | ✓ | ✗ | +| Manage private sources | ✓ | ✓ | ✗ | +| Rename teamspace | ✓ | ✗ | ✗ | +| Delete teamspace | ✓ | ✗ | ✗ | + +## Inviting Members + + + + Enter the email address of the person you want to invite. + + + Choose **Developer** or **Admin**. + + + Click **Add**. The member receives an invitation email and is automatically added to the teamspace once they sign in. + + + +The invitation will remain pending until they sign in. + +## Teamspace Settings + +If you are the owner of the teamspace, you can rename or delete the teamspace under the overview tab. + +![Teamspace management card](/images/dashboard/teamspace-management.png) + +Deleting a teamspace is permanent. All members lose access immediately. + +## Limits + +| Plan | Max Members | +| ---------- | ----------------- | +| Free | 1 (personal only) | +| Pro | 10 | +| Enterprise | Unlimited | diff --git a/docs/howto/usage.mdx b/docs/howto/usage.mdx new file mode 100644 index 0000000..dcb7e0d --- /dev/null +++ b/docs/howto/usage.mdx @@ -0,0 +1,40 @@ +--- +title: Monitor Usage +description: Monitor your Context7 API usage and track costs +--- + +Track your Context7 usage with real-time metrics from the **Overview** tab on your teamspace dashboard. + +![Usage statistics card showing requests, parsing tokens, seats, and cost breakdown](/images/dashboard/usage-stats.png) + +## Metrics Overview + +The Overview tab displays four metrics: + +### Requests + +The total number of API calls made to Context7, shown against your plan's included quota. Requests within your quota are free; excess requests are billed based on your plan. + +### Parsing Tokens + +The total tokens processed when parsing private source documentation (Pro and Enterprise only). + +- Charged when adding a new private source +- Charged for changed content when refreshing +- No charge for cached content when refreshing + +### Seats + +The number of members in your teamspace. Each seat is billed monthly based on your plan. + +### Cost + +Your total monthly cost in USD, with a breakdown of each component: request overages, parsing tokens, and seats. + +See [Plans & Pricing](https://context7.com/plans) for current rates and included quotas. + +## Reporting Periods + +**Free Plan**: Metrics display daily usage (resets every 24 hours) + +**Pro & Enterprise Plans**: Metrics display monthly usage (resets on your billing date) diff --git a/docs/howto/verification.mdx b/docs/howto/verification.mdx new file mode 100644 index 0000000..339c657 --- /dev/null +++ b/docs/howto/verification.mdx @@ -0,0 +1,153 @@ +--- +title: Verify Your Library +description: Get your library verified to increase visibility and build trust with developers +--- + +Verified libraries receive a special badge that signals quality and trustworthiness to developers. Verification helps your library rank higher in search results and gives users confidence that your documentation is reliable. + +Only library owners can apply for verification. You must [claim your library](/howto/claiming-libraries) before applying. + +## Why Get Verified? + +Verification provides several benefits for your library: + +- **Higher search ranking**: Verified libraries are prioritized in search results and recommendations +- **Trust badge**: A verified badge is displayed on your library page, building confidence with users +- **Increased visibility**: Verified libraries appear more prominently across Context7 +- **Broader access**: Teamspaces can restrict their library access to "verified only" - without verification, your library won't be accessible to these users + +## Verification Badge + +Once verified, your library displays a green checkmark badge next to its name: + + + Verified badge on library + + +This badge appears on: +- Your library's main page +- Search results +- Library listings and tables + +## How to Get Verified + +There are two paths to verification: + +### Automatic Verification + +Libraries are automatically verified when they meet certain quality thresholds: + +- **High trust score**: Libraries with a trust score of 9 or above. Trust score is calculated based on the GitHub organization/user profile, considering factors like total stars, number of repositories, account age, recent activity, followers, and profile completeness. +- **Top 100 libraries**: Most-used libraries by API requests + +Automatic verification is checked daily. If your library qualifies, it will be verified automatically without any action required. + +### Manual Verification + +If your library doesn't qualify for automatic verification, you can apply manually: + + + + You must be a verified owner of the library. See [Claim Your Library](/howto/claiming-libraries) for instructions. + + + + Navigate to your library's admin page at: + + ``` + https://context7.com/{owner}/{repo}/admin + ``` + + + + If your library is not yet verified, you'll see a banner at the top of the configuration page with an "Apply for Verification" button. Click it to start the process. + + + Apply for Verification button + + + + + When you initiate a verification request, Context7 automatically checks a set of quality criteria. If your library meets **any one** of the following criteria, it is verified instantly — no form required: + + - **Trust score above 7**: Calculated from your GitHub organization/user profile, including stars, repository count, account age, recent activity, followers, and profile completeness. + - **250+ GitHub stars** *(repositories only)*: Indicates a strong and established community. + - **Top 1% by popularity ranking**: Your library is among the most in-demand sources indexed on Context7. + - **200+ referring domains** *(websites and llms.txt sources only)*: Your source is cited or linked to by more than 200 unique external domains, demonstrating broad recognition across the web. + + If any of these thresholds are met, verification is granted immediately. + + + + If none of the quality thresholds are met, you'll be prompted to fill out the verification application form: + + | Field | Description | Required | + | --- | --- | --- | + | **Website/Docs URL** | Link to your library's official website or documentation | Yes | + | **Library Description** | Brief description of what your library does | Yes | + | **Developer Value** | How your library helps developers | No | + + + Verification application modal + + + + + Click "Submit Application" to send your request. Your application will be reviewed immediately. + + + +## Verification Requirements + +To be approved for manual verification, your library should: + +- **Be a legitimate project**: Real libraries with actual users and documentation +- **Have quality documentation**: Well-organized, up-to-date documentation that helps developers +- **Be actively maintained**: Regular updates and responsive to issues +- **Follow best practices**: Clear README, proper licensing, and good code organization + + + Verification is free and always will be. We verify libraries based on quality, not payment. + + +## Verification Status + +You can check your library's verification status on the admin page: + +| Status | Description | +| --- | --- | +| **Verified** | Green badge displayed, full verification benefits | +| **Not Verified** | No badge, apply to get verified | + +## FAQ + +### How long does manual verification take? + +If your library meets one of the quality thresholds, verification is instant. Otherwise, your application is reviewed immediately after submission. If it's not automatically accepted, you can [open a GitHub issue](https://github.com/upstash/context7/issues/new/choose) to request a manual review. + +### Can verification be revoked? + +Yes, in rare cases. Verification may be revoked if: +- The library becomes abandoned or unmaintained +- Documentation quality significantly degrades +- The library violates Context7's terms of service + +### Does verification cost anything? + +No. Verification is completely free and based solely on library quality. + +### I was automatically verified. Can I lose it? + +Automatic verification is recalculated daily. If your library no longer meets the automatic criteria, you'll retain your verification status but may need to apply manually if it's ever revoked. + +### My library is popular but not verified. Why? + +Automatic verification considers multiple factors including trust score and usage statistics. When you apply manually, Context7 also checks quality criteria like GitHub stars, popularity ranking, and referring domains. If you believe your library meets any of these thresholds, please apply manually and the check will run immediately. + +## Need Help? + +If you have questions about verification or encounter issues with the application process: + +- [Open a GitHub issue](https://github.com/upstash/context7/issues/new/choose) +- Join our [Discord community](https://upstash.com/discord) +- Contact us at [support@context7.com](mailto:support@context7.com) diff --git a/docs/images/clients/claude-code/mcp-details.png b/docs/images/clients/claude-code/mcp-details.png new file mode 100644 index 0000000..f4e5b21 Binary files /dev/null and b/docs/images/clients/claude-code/mcp-details.png differ diff --git a/docs/images/clients/claude-code/mcp-list.png b/docs/images/clients/claude-code/mcp-list.png new file mode 100644 index 0000000..49b23cb Binary files /dev/null and b/docs/images/clients/claude-code/mcp-list.png differ diff --git a/docs/images/clients/claude-code/mcp-unauthenticated.png b/docs/images/clients/claude-code/mcp-unauthenticated.png new file mode 100644 index 0000000..cef670e Binary files /dev/null and b/docs/images/clients/claude-code/mcp-unauthenticated.png differ diff --git a/docs/images/clients/cursor/logo.png b/docs/images/clients/cursor/logo.png new file mode 100644 index 0000000..690b4c3 Binary files /dev/null and b/docs/images/clients/cursor/logo.png differ diff --git a/docs/images/clients/cursor/mcp-settings.png b/docs/images/clients/cursor/mcp-settings.png new file mode 100644 index 0000000..30cad4f Binary files /dev/null and b/docs/images/clients/cursor/mcp-settings.png differ diff --git a/docs/images/clients/cursor/rules.png b/docs/images/clients/cursor/rules.png new file mode 100644 index 0000000..ec975fd Binary files /dev/null and b/docs/images/clients/cursor/rules.png differ diff --git a/docs/images/dashboard/add-payment-method.png b/docs/images/dashboard/add-payment-method.png new file mode 100644 index 0000000..4f55844 Binary files /dev/null and b/docs/images/dashboard/add-payment-method.png differ diff --git a/docs/images/dashboard/admin/claim-library-button.png b/docs/images/dashboard/admin/claim-library-button.png new file mode 100644 index 0000000..790a9fa Binary files /dev/null and b/docs/images/dashboard/admin/claim-library-button.png differ diff --git a/docs/images/dashboard/admin/claim-modal.png b/docs/images/dashboard/admin/claim-modal.png new file mode 100644 index 0000000..45e8b0f Binary files /dev/null and b/docs/images/dashboard/admin/claim-modal.png differ diff --git a/docs/images/dashboard/admin/config-overview.png b/docs/images/dashboard/admin/config-overview.png new file mode 100644 index 0000000..883c331 Binary files /dev/null and b/docs/images/dashboard/admin/config-overview.png differ diff --git a/docs/images/dashboard/admin/library-manage-button.png b/docs/images/dashboard/admin/library-manage-button.png new file mode 100644 index 0000000..2cbacfa Binary files /dev/null and b/docs/images/dashboard/admin/library-manage-button.png differ diff --git a/docs/images/dashboard/admin/library-metrics.png b/docs/images/dashboard/admin/library-metrics.png new file mode 100644 index 0000000..83f53d1 Binary files /dev/null and b/docs/images/dashboard/admin/library-metrics.png differ diff --git a/docs/images/dashboard/admin/managing-versions.png b/docs/images/dashboard/admin/managing-versions.png new file mode 100644 index 0000000..46c03a4 Binary files /dev/null and b/docs/images/dashboard/admin/managing-versions.png differ diff --git a/docs/images/dashboard/api-keys-card.png b/docs/images/dashboard/api-keys-card.png new file mode 100644 index 0000000..c1225a7 Binary files /dev/null and b/docs/images/dashboard/api-keys-card.png differ diff --git a/docs/images/dashboard/billing-page.png b/docs/images/dashboard/billing-page.png new file mode 100644 index 0000000..c968652 Binary files /dev/null and b/docs/images/dashboard/billing-page.png differ diff --git a/docs/images/dashboard/chat-widget.png b/docs/images/dashboard/chat-widget.png new file mode 100644 index 0000000..6250825 Binary files /dev/null and b/docs/images/dashboard/chat-widget.png differ diff --git a/docs/images/dashboard/manage-cards.png b/docs/images/dashboard/manage-cards.png new file mode 100644 index 0000000..c8969e9 Binary files /dev/null and b/docs/images/dashboard/manage-cards.png differ diff --git a/docs/images/dashboard/members-tab.png b/docs/images/dashboard/members-tab.png new file mode 100644 index 0000000..333278e Binary files /dev/null and b/docs/images/dashboard/members-tab.png differ diff --git a/docs/images/dashboard/private-sources-card.png b/docs/images/dashboard/private-sources-card.png new file mode 100644 index 0000000..e6317ff Binary files /dev/null and b/docs/images/dashboard/private-sources-card.png differ diff --git a/docs/images/dashboard/public-repository-filters.png b/docs/images/dashboard/public-repository-filters.png new file mode 100644 index 0000000..c6e4b6a Binary files /dev/null and b/docs/images/dashboard/public-repository-filters.png differ diff --git a/docs/images/dashboard/source-type-access.png b/docs/images/dashboard/source-type-access.png new file mode 100644 index 0000000..3f02ab5 Binary files /dev/null and b/docs/images/dashboard/source-type-access.png differ diff --git a/docs/images/dashboard/teamspace-management.png b/docs/images/dashboard/teamspace-management.png new file mode 100644 index 0000000..db379c1 Binary files /dev/null and b/docs/images/dashboard/teamspace-management.png differ diff --git a/docs/images/dashboard/usage-stats.png b/docs/images/dashboard/usage-stats.png new file mode 100644 index 0000000..bfd1e4a Binary files /dev/null and b/docs/images/dashboard/usage-stats.png differ diff --git a/docs/images/dashboard/user-dropdown.png b/docs/images/dashboard/user-dropdown.png new file mode 100644 index 0000000..c1545ee Binary files /dev/null and b/docs/images/dashboard/user-dropdown.png differ diff --git a/docs/images/enterprise/api-keys/api-keys-create-dialog.png b/docs/images/enterprise/api-keys/api-keys-create-dialog.png new file mode 100644 index 0000000..91bc1b2 Binary files /dev/null and b/docs/images/enterprise/api-keys/api-keys-create-dialog.png differ diff --git a/docs/images/enterprise/api-keys/api-keys-created.png b/docs/images/enterprise/api-keys/api-keys-created.png new file mode 100644 index 0000000..6a52f82 Binary files /dev/null and b/docs/images/enterprise/api-keys/api-keys-created.png differ diff --git a/docs/images/enterprise/api-keys/api-keys-empty.png b/docs/images/enterprise/api-keys/api-keys-empty.png new file mode 100644 index 0000000..55c15e8 Binary files /dev/null and b/docs/images/enterprise/api-keys/api-keys-empty.png differ diff --git a/docs/images/enterprise/enterprise-managed-auth/context7-ema-config.png b/docs/images/enterprise/enterprise-managed-auth/context7-ema-config.png new file mode 100644 index 0000000..2bb1394 Binary files /dev/null and b/docs/images/enterprise/enterprise-managed-auth/context7-ema-config.png differ diff --git a/docs/images/enterprise/enterprise-managed-auth/okta-assignments.png b/docs/images/enterprise/enterprise-managed-auth/okta-assignments.png new file mode 100644 index 0000000..2c07f30 Binary files /dev/null and b/docs/images/enterprise/enterprise-managed-auth/okta-assignments.png differ diff --git a/docs/images/enterprise/enterprise-managed-auth/okta-enable-feature.png b/docs/images/enterprise/enterprise-managed-auth/okta-enable-feature.png new file mode 100644 index 0000000..1abaf02 Binary files /dev/null and b/docs/images/enterprise/enterprise-managed-auth/okta-enable-feature.png differ diff --git a/docs/images/enterprise/enterprise-managed-auth/okta-manage-connections.png b/docs/images/enterprise/enterprise-managed-auth/okta-manage-connections.png new file mode 100644 index 0000000..a3b2f0a Binary files /dev/null and b/docs/images/enterprise/enterprise-managed-auth/okta-manage-connections.png differ diff --git a/docs/images/enterprise/enterprise-managed-auth/okta-requesting-app.png b/docs/images/enterprise/enterprise-managed-auth/okta-requesting-app.png new file mode 100644 index 0000000..8440035 Binary files /dev/null and b/docs/images/enterprise/enterprise-managed-auth/okta-requesting-app.png differ diff --git a/docs/images/enterprise/enterprise-managed-auth/okta-resource-app.png b/docs/images/enterprise/enterprise-managed-auth/okta-resource-app.png new file mode 100644 index 0000000..1078e1f Binary files /dev/null and b/docs/images/enterprise/enterprise-managed-auth/okta-resource-app.png differ diff --git a/docs/images/enterprise/entra-sso/01-register-app.png b/docs/images/enterprise/entra-sso/01-register-app.png new file mode 100644 index 0000000..20d2148 Binary files /dev/null and b/docs/images/enterprise/entra-sso/01-register-app.png differ diff --git a/docs/images/enterprise/entra-sso/02-app-overview.png b/docs/images/enterprise/entra-sso/02-app-overview.png new file mode 100644 index 0000000..99205a8 Binary files /dev/null and b/docs/images/enterprise/entra-sso/02-app-overview.png differ diff --git a/docs/images/enterprise/entra-sso/03-client-secret.png b/docs/images/enterprise/entra-sso/03-client-secret.png new file mode 100644 index 0000000..780fe6d Binary files /dev/null and b/docs/images/enterprise/entra-sso/03-client-secret.png differ diff --git a/docs/images/enterprise/entra-sso/04-app-roles.png b/docs/images/enterprise/entra-sso/04-app-roles.png new file mode 100644 index 0000000..8667183 Binary files /dev/null and b/docs/images/enterprise/entra-sso/04-app-roles.png differ diff --git a/docs/images/enterprise/entra-sso/05-assignment-required.png b/docs/images/enterprise/entra-sso/05-assignment-required.png new file mode 100644 index 0000000..a937f7a Binary files /dev/null and b/docs/images/enterprise/entra-sso/05-assignment-required.png differ diff --git a/docs/images/enterprise/entra-sso/06-assign-user-role.png b/docs/images/enterprise/entra-sso/06-assign-user-role.png new file mode 100644 index 0000000..f929ff2 Binary files /dev/null and b/docs/images/enterprise/entra-sso/06-assign-user-role.png differ diff --git a/docs/images/enterprise/entra-sso/07-context7-settings-card.png b/docs/images/enterprise/entra-sso/07-context7-settings-card.png new file mode 100644 index 0000000..f3d5880 Binary files /dev/null and b/docs/images/enterprise/entra-sso/07-context7-settings-card.png differ diff --git a/docs/images/enterprise/entra-sso/08-filled-credentials.png b/docs/images/enterprise/entra-sso/08-filled-credentials.png new file mode 100644 index 0000000..b7167f3 Binary files /dev/null and b/docs/images/enterprise/entra-sso/08-filled-credentials.png differ diff --git a/docs/images/enterprise/entra-sso/10-login-page.png b/docs/images/enterprise/entra-sso/10-login-page.png new file mode 100644 index 0000000..a5b3528 Binary files /dev/null and b/docs/images/enterprise/entra-sso/10-login-page.png differ diff --git a/docs/images/enterprise/entra-sso/11-users-tab.png b/docs/images/enterprise/entra-sso/11-users-tab.png new file mode 100644 index 0000000..2a4066e Binary files /dev/null and b/docs/images/enterprise/entra-sso/11-users-tab.png differ diff --git a/docs/images/enterprise/entra-sso/README.md b/docs/images/enterprise/entra-sso/README.md new file mode 100644 index 0000000..f9f28e2 --- /dev/null +++ b/docs/images/enterprise/entra-sso/README.md @@ -0,0 +1,188 @@ +# Entra SSO screenshots + +Checklist and capture instructions for the 11 screenshots referenced in +`docs/enterprise/security/entra-sso.mdx`. Drop the finished PNGs into this +folder using the exact filenames below. Each screenshot should capture only +the relevant Azure blade or Context7 card (crop out the surrounding Azure +sidebar when it isn't load-bearing for the step). + +Suggested viewport: **1440x900**, browser zoom 100%, light theme. + +--- + +## 01-register-app.png + +**Where**: Azure Portal → Microsoft Entra ID → Manage → App registrations → +**+ New registration**. + +**What to capture**: the New registration form with these fields filled in: + +- **Name**: `Context7` +- **Supported account types**: *Accounts in this organizational directory only* +- **Redirect URI**: `Web` + `http://localhost:3000/api/auth/entra/callback` + (or your real host) + +Keep the **Register** button visible at the bottom so readers see the +submit action. + +--- + +## 02-app-overview.png + +**Where**: Azure Portal → App registrations → **Context7** → **Overview**. + +**What to capture**: the Essentials panel showing **Application (client) ID** +and **Directory (tenant) ID** clearly. Values don't need to be redacted since +they're not secrets, but blur them if you'd rather not expose your real +tenant. + +Crop tight to the Essentials block so both IDs are easy to spot. + +--- + +## 03-client-secret.png + +**Where**: Azure Portal → App registrations → Context7 → **Certificates & +secrets** → **Client secrets** tab → **+ New client secret**. + +**What to capture**: the *Add a client secret* side panel showing the +description field filled in (for example, `Context7 on-prem`) and an +expiry selected. You don't need to show the secret Value itself (and +probably shouldn't). + +An alternative, if the create panel feels too modal-heavy: take the shot +after the secret is created, showing the row in the Client secrets table +with the **Value** column highlighted (but redact the actual secret). + +--- + +## 04-app-roles.png + +**Where**: Azure Portal → App registrations → Context7 → **App roles**. + +**What to capture**: the App roles list with both roles created and +**Enabled** = true: + +- `Context7 Admin` / Value: `Context7.Admin` +- `Context7 Member` / Value: `Context7.Member` + +Make sure both rows are visible in a single shot so readers see the pair. + +--- + +## 05-assignment-required.png + +**Where**: Azure Portal → **Microsoft Entra ID** → Enterprise applications +→ Context7 → **Properties**. + +**What to capture**: the Properties page with **Assignment required?** set +to **Yes**. Include the **Save** button at the top so readers know they +need to save. + +Note: this is the *Enterprise applications* view, not App registrations. +Worth showing enough sidebar context to make that obvious. + +--- + +## 06-assign-user-role.png + +**Where**: Enterprise applications → Context7 → **Users and groups** → +**+ Add user/group**. + +**What to capture**: the *Add Assignment* page with: + +- **Users**: one user selected (your own name is fine) +- **Select a role**: **Context7 Admin** (or Member, either is fine) + +The role picker side panel being visible in the same shot is ideal so +readers see where to click for the role selection. + +--- + +## 07-context7-settings-card.png + +**Where**: Context7 dashboard → **Workspace Settings** → scroll to the +**Authentication** section. + +**What to capture**: the entire **Microsoft Entra SSO** card with the +sticky **On this page** nav visible on the right. Toggle should be **off** +and status indicator should read *Not configured*. + +This is the "empty state" screenshot. All fields blank. + +--- + +## 08-filled-credentials.png + +**Where**: same card, after pasting in values. + +**What to capture**: the card with: + +- **Tenant ID** filled in +- **Client ID** filled in +- **Client Secret**: either shows "Leave blank to keep the current secret" + with the green "A client secret is already stored" check, or a fresh + secret paste (redact the actual secret before taking the screenshot) +- **Admin role value**: `Context7.Admin` +- **Member role value**: `Context7.Member` + +Toggle can stay off at this point. Status should read *Configured · Toggle +on to show the sign-in button*. + +--- + +## 09-test-success.png + +**Where**: same card, after clicking **Test connection**. + +**What to capture**: the green success banner *Connection verified with +Microsoft Entra.* right above the Save/Test buttons, with the filled-in +form still visible above it. + +--- + +## 10-login-page.png + +**Where**: open `/login` in an incognito window after SSO has been enabled +(toggle on + saved). + +**What to capture**: the full login card showing: + +- Context7 wordmark at the top +- **Welcome back** heading +- **Continue with Microsoft Entra ID** button with the four-square logo +- *OR WITH PASSWORD* divider +- Username + password form below + +Center the card in the frame. Incognito avoids any auto-fill suggestions +cluttering the fields. + +--- + +## 11-users-tab.png + +**Where**: Workspace Settings → **Users** tab, after at least one Entra +user has signed in once. + +**What to capture**: the Users table showing a mix of providers: + +- The seeded `admin` row with `password` under AUTH +- At least one Entra user with `entra` under AUTH, display name, email, + and a recent **last login** timestamp + +A minimum of two rows makes the mixed-provider story land. Redact email +domains if they're sensitive. + +--- + +## Tips + +- **File format**: PNG. Avoid JPEG for UI screenshots; text gets fuzzy. +- **Retina**: capture at the native device pixel ratio, then downscale if + needed. Don't upscale low-DPI shots. +- **Redaction**: use a solid rectangle in a matching background color + rather than blur when hiding values. Blur often leaks readable pixels + when rendered small. +- **Consistency**: try to keep the same browser chrome, zoom level, and + theme across the Azure shots and across the Context7 shots so the + gallery looks cohesive. diff --git a/docs/images/enterprise/gitops/gitops-settings.png b/docs/images/enterprise/gitops/gitops-settings.png new file mode 100644 index 0000000..028fa7a Binary files /dev/null and b/docs/images/enterprise/gitops/gitops-settings.png differ diff --git a/docs/images/enterprise/integrations/confluence-add.png b/docs/images/enterprise/integrations/confluence-add.png new file mode 100644 index 0000000..bc1a596 Binary files /dev/null and b/docs/images/enterprise/integrations/confluence-add.png differ diff --git a/docs/images/enterprise/integrations/confluence-settings.png b/docs/images/enterprise/integrations/confluence-settings.png new file mode 100644 index 0000000..fec5faf Binary files /dev/null and b/docs/images/enterprise/integrations/confluence-settings.png differ diff --git a/docs/images/enterprise/integrations/confluence-source.png b/docs/images/enterprise/integrations/confluence-source.png new file mode 100644 index 0000000..14b6061 Binary files /dev/null and b/docs/images/enterprise/integrations/confluence-source.png differ diff --git a/docs/images/enterprise/integrations/git-tokens.png b/docs/images/enterprise/integrations/git-tokens.png new file mode 100644 index 0000000..6b2b3df Binary files /dev/null and b/docs/images/enterprise/integrations/git-tokens.png differ diff --git a/docs/images/enterprise/integrations/github-app.png b/docs/images/enterprise/integrations/github-app.png new file mode 100644 index 0000000..78cb27c Binary files /dev/null and b/docs/images/enterprise/integrations/github-app.png differ diff --git a/docs/images/enterprise/integrations/github-permissions.png b/docs/images/enterprise/integrations/github-permissions.png new file mode 100644 index 0000000..2058db5 Binary files /dev/null and b/docs/images/enterprise/integrations/github-permissions.png differ diff --git a/docs/images/enterprise/integrations/github-webhook.png b/docs/images/enterprise/integrations/github-webhook.png new file mode 100644 index 0000000..8d1eeb6 Binary files /dev/null and b/docs/images/enterprise/integrations/github-webhook.png differ diff --git a/docs/images/enterprise/library-import/export-menu.png b/docs/images/enterprise/library-import/export-menu.png new file mode 100644 index 0000000..825dad6 Binary files /dev/null and b/docs/images/enterprise/library-import/export-menu.png differ diff --git a/docs/images/enterprise/library-import/export-select.png b/docs/images/enterprise/library-import/export-select.png new file mode 100644 index 0000000..fb28ed1 Binary files /dev/null and b/docs/images/enterprise/library-import/export-select.png differ diff --git a/docs/images/enterprise/library-import/import-source.png b/docs/images/enterprise/library-import/import-source.png new file mode 100644 index 0000000..4052d25 Binary files /dev/null and b/docs/images/enterprise/library-import/import-source.png differ diff --git a/docs/images/enterprise/library-import/import-upload.png b/docs/images/enterprise/library-import/import-upload.png new file mode 100644 index 0000000..9bb7f4e Binary files /dev/null and b/docs/images/enterprise/library-import/import-upload.png differ diff --git a/docs/images/enterprise/library-import/imported-badge.png b/docs/images/enterprise/library-import/imported-badge.png new file mode 100644 index 0000000..a4451df Binary files /dev/null and b/docs/images/enterprise/library-import/imported-badge.png differ diff --git a/docs/images/enterprise/oidc-sso/01-login-page.png b/docs/images/enterprise/oidc-sso/01-login-page.png new file mode 100644 index 0000000..d73702e Binary files /dev/null and b/docs/images/enterprise/oidc-sso/01-login-page.png differ diff --git a/docs/images/enterprise/oidc-sso/02-sso-card-oidc.png b/docs/images/enterprise/oidc-sso/02-sso-card-oidc.png new file mode 100644 index 0000000..ef8867d Binary files /dev/null and b/docs/images/enterprise/oidc-sso/02-sso-card-oidc.png differ diff --git a/docs/images/enterprise/oidc-sso/03-group-mapping.png b/docs/images/enterprise/oidc-sso/03-group-mapping.png new file mode 100644 index 0000000..b897032 Binary files /dev/null and b/docs/images/enterprise/oidc-sso/03-group-mapping.png differ diff --git a/docs/images/enterprise/oidc-sso/04-password-card.png b/docs/images/enterprise/oidc-sso/04-password-card.png new file mode 100644 index 0000000..9ee95a9 Binary files /dev/null and b/docs/images/enterprise/oidc-sso/04-password-card.png differ diff --git a/docs/images/enterprise/oidc-sso/05-users-tab.png b/docs/images/enterprise/oidc-sso/05-users-tab.png new file mode 100644 index 0000000..cbaecd3 Binary files /dev/null and b/docs/images/enterprise/oidc-sso/05-users-tab.png differ diff --git a/docs/images/howto/verification/apply-button.png b/docs/images/howto/verification/apply-button.png new file mode 100644 index 0000000..b8e0b70 Binary files /dev/null and b/docs/images/howto/verification/apply-button.png differ diff --git a/docs/images/howto/verification/apply-modal.png b/docs/images/howto/verification/apply-modal.png new file mode 100644 index 0000000..6382585 Binary files /dev/null and b/docs/images/howto/verification/apply-modal.png differ diff --git a/docs/images/howto/verification/verification-badge.png b/docs/images/howto/verification/verification-badge.png new file mode 100644 index 0000000..f4a2e13 Binary files /dev/null and b/docs/images/howto/verification/verification-badge.png differ diff --git a/docs/images/integrations/coderabbit/add-server-modal.png b/docs/images/integrations/coderabbit/add-server-modal.png new file mode 100644 index 0000000..df08e32 Binary files /dev/null and b/docs/images/integrations/coderabbit/add-server-modal.png differ diff --git a/docs/images/integrations/coderabbit/integrations-tab.png b/docs/images/integrations/coderabbit/integrations-tab.png new file mode 100644 index 0000000..6e3b09f Binary files /dev/null and b/docs/images/integrations/coderabbit/integrations-tab.png differ diff --git a/docs/images/integrations/coderabbit/server-connected.png b/docs/images/integrations/coderabbit/server-connected.png new file mode 100644 index 0000000..a1d28bb Binary files /dev/null and b/docs/images/integrations/coderabbit/server-connected.png differ diff --git a/docs/images/integrations/coderabbit/update-mcp-settings.png b/docs/images/integrations/coderabbit/update-mcp-settings.png new file mode 100644 index 0000000..ad1804a Binary files /dev/null and b/docs/images/integrations/coderabbit/update-mcp-settings.png differ diff --git a/docs/images/integrations/tembo/integrations-page.png b/docs/images/integrations/tembo/integrations-page.png new file mode 100644 index 0000000..0b440c0 Binary files /dev/null and b/docs/images/integrations/tembo/integrations-page.png differ diff --git a/docs/images/integrations/tembo/server-connected.png b/docs/images/integrations/tembo/server-connected.png new file mode 100644 index 0000000..2c9a6d3 Binary files /dev/null and b/docs/images/integrations/tembo/server-connected.png differ diff --git a/docs/images/on-premise-architecture.png b/docs/images/on-premise-architecture.png new file mode 100644 index 0000000..943823e Binary files /dev/null and b/docs/images/on-premise-architecture.png differ diff --git a/docs/images/security/classifier_pipeline.png b/docs/images/security/classifier_pipeline.png new file mode 100644 index 0000000..9907cdf Binary files /dev/null and b/docs/images/security/classifier_pipeline.png differ diff --git a/docs/installation.mdx b/docs/installation.mdx new file mode 100644 index 0000000..777012d --- /dev/null +++ b/docs/installation.mdx @@ -0,0 +1,5 @@ +--- +title: Installation +url: https://github.com/upstash/context7#installation +--- + diff --git a/docs/integrations/code-rabbit.mdx b/docs/integrations/code-rabbit.mdx new file mode 100644 index 0000000..bb893c4 --- /dev/null +++ b/docs/integrations/code-rabbit.mdx @@ -0,0 +1,62 @@ +--- +title: CodeRabbit +sidebarTitle: CodeRabbit +description: AI-powered code review tool +--- + +[CodeRabbit](https://coderabbit.ai) is an AI-powered code review tool that automatically reviews pull requests. By connecting Context7 as an MCP server, CodeRabbit can access up-to-date library documentation during reviews, helping it verify implementations against the latest API references and best practices. + +## Setup + + + + Go to your [CodeRabbit dashboard](https://app.coderabbit.ai) and navigate to **Integrations** → **MCP Servers**. + + ![Integrations tab](/images/integrations/coderabbit/integrations-tab.png) + + + Click the **Add** button next to **Context7** MCP server. + + Add the following header for higher rate limits: + + | Header | Value | + |--------|-------| + | `CONTEXT7_API_KEY` | Your API key from the [Context7 dashboard](https://context7.com/dashboard) | + + ```json + { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + ``` + + ![Add server modal](/images/integrations/coderabbit/add-server-modal.png) + + + Click the **Connect** button to connect the server. + + ![Server connected](/images/integrations/coderabbit/server-connected.png) + + + To use Context7 with public repositories, go to **Organization Settings** → **Configuration** → **Knowledge Base**. In the MCP section, select **Enabled** instead of **Auto** and click **Apply Changes**. + + ![Update MCP settings](/images/integrations/coderabbit/update-mcp-settings.png) + + + +## Usage Guidance + +In the **Usage Guidance** field, you can instruct CodeRabbit on how to use Context7 during reviews. For example: + +``` +Use Context7 to look up documentation for any libraries used in the code being reviewed. +Verify that API usage matches the latest documentation and flag any deprecated patterns. +``` + +## How It Works + +Once connected, CodeRabbit will query Context7 for relevant library documentation when reviewing pull requests. This helps CodeRabbit: + +- Verify correct API usage against the latest documentation +- Identify deprecated methods or patterns +- Suggest improvements based on library best practices +- Provide more accurate and informed review comments diff --git a/docs/integrations/factory-ai.mdx b/docs/integrations/factory-ai.mdx new file mode 100644 index 0000000..4d34370 --- /dev/null +++ b/docs/integrations/factory-ai.mdx @@ -0,0 +1,50 @@ +--- +title: Factory AI +sidebarTitle: Factory AI +description: AI-native software development platform with Droids +--- + +[Factory AI](https://factory.ai) is a coding agent platform that uses "Droids" to handle development tasks. By connecting Context7 as an MCP server, Factory Droids can access up-to-date library documentation during coding tasks. + +For more details on how Factory AI handles MCP, see the [Factory AI MCP documentation](https://docs.factory.ai/cli/configuration/mcp). + +## Setup + +There are multiple ways to add Context7 as an MCP server in Factory AI. Replace `YOUR_API_KEY` with your API key from the [Context7 dashboard](https://context7.com/dashboard). + +### Using the CLI + +```bash +droid mcp add context7 https://mcp.context7.com/mcp --type http --header "CONTEXT7_API_KEY: YOUR_API_KEY" +``` + +### Using the MCP Manager + +Run the `/mcp` command inside Factory and add Context7 from the interface. + +### Using a Configuration File + +Add Context7 directly to your `.factory/mcp.json` (project-level) or `~/.factory/mcp.json` (user-level): + +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +## How It Works + +Once connected, Factory Droids will query Context7 for relevant library documentation during coding tasks. This helps Droids: + +- Use correct API signatures and patterns from the latest documentation +- Avoid deprecated methods or outdated usage patterns +- Generate implementations aligned with library best practices +- Produce higher-quality code with fewer revision cycles diff --git a/docs/integrations/github-actions.mdx b/docs/integrations/github-actions.mdx new file mode 100644 index 0000000..d39482c --- /dev/null +++ b/docs/integrations/github-actions.mdx @@ -0,0 +1,81 @@ +--- +title: GitHub Actions +sidebarTitle: GitHub Actions +description: Automatically refresh your Context7 library when your docs change +--- + +Keep your Context7 documentation in sync by triggering a refresh whenever you push to your main branch. + +## Setup + + + + Go to your [Context7 dashboard](https://context7.com/dashboard) and copy your API key. + + + In your GitHub repository, go to **Settings** → **Secrets and variables** → **Actions** and add a new secret: + + | Name | Value | + |------|-------| + | `CONTEXT7_API_KEY` | Your API key from the Context7 dashboard | + + + Add the following file to your repository at `.github/workflows/context7-refresh.yml`: + + ```yaml + name: Refresh Context7 Docs + + on: + push: + branches: + - master # change to your default branch if different + + jobs: + refresh: + runs-on: ubuntu-latest + steps: + - name: Trigger Context7 Refresh + run: | + curl -s -X POST https://context7.com/api/v1/refresh \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${{ secrets.CONTEXT7_API_KEY }}" \ + -d '{"libraryName": "/${{ github.repository }}"}' + ``` + + This uses `${{ github.repository }}` to automatically resolve to your repository's `owner/repo` (e.g., `vercel/next.js`). If your library ID on Context7 differs from your GitHub repository name, replace it with the correct value (e.g., `/your-org/your-repo`). + + + +## Refreshing a Specific Branch + +To refresh a non-default branch, add the `branch` field to the request body. The `branch` value must match a branch name that already exists on your library in Context7. + +```yaml +- name: Trigger Context7 Refresh + run: | + curl -s -X POST https://context7.com/api/v1/refresh \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${{ secrets.CONTEXT7_API_KEY }}" \ + -d '{"libraryName": "/your-org/your-repo", "branch": "v2"}' +``` + + + If the branch has not been added to your library on Context7, the refresh will fail with a `branch_not_found` error. + + +## Private Repositories + +For private repositories, include a `gitToken` so Context7 can access your code: + +```yaml +- name: Trigger Context7 Refresh + run: | + curl -s -X POST https://context7.com/api/v1/refresh \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${{ secrets.CONTEXT7_API_KEY }}" \ + -d '{"libraryName": "/your-org/your-repo", "gitToken": "${{ secrets.GIT_ACCESS_TOKEN }}"}' +``` + + + Private sources require a Pro or Enterprise plan. See the [Private Sources](/howto/private-sources) guide for more details. + diff --git a/docs/integrations/mastra.mdx b/docs/integrations/mastra.mdx new file mode 100644 index 0000000..afba586 --- /dev/null +++ b/docs/integrations/mastra.mdx @@ -0,0 +1,68 @@ +--- +title: Mastra +sidebarTitle: Mastra +description: TypeScript framework for building AI agents +--- + +[Mastra](https://mastra.ai) is a TypeScript framework for building AI agents. It provides first-class MCP support through its `MCPClient` class. By connecting Context7 as an MCP server, your Mastra agents can access up-to-date library documentation, enabling them to generate accurate code and answer technical questions with current API references. + +For more details on how Mastra handles MCP, see the [Mastra MCP documentation](https://mastra.ai/docs/mcp/overview). + +## Setup + + + + Add the Mastra MCP package to your project: + + ```bash + npm install @mastra/mcp@latest + ``` + + + Configure an `MCPClient` that connects to Context7: + + ```typescript + import { MCPClient } from "@mastra/mcp"; + + const context7 = new MCPClient({ + id: "context7", + servers: { + context7: { + url: new URL("https://mcp.context7.com/mcp"), + requestInit: { + headers: { + CONTEXT7_API_KEY: process.env.CONTEXT7_API_KEY!, + }, + }, + }, + }, + }); + ``` + + Set `CONTEXT7_API_KEY` in your environment with your API key from the [Context7 dashboard](https://context7.com/dashboard). + + + Pass the Context7 tools to your Mastra agent: + + ```typescript + import { Agent } from "@mastra/core/agent"; + + const agent = new Agent({ + id: "coding-assistant", + name: "Coding Assistant", + instructions: "You are a helpful coding assistant with access to up-to-date library documentation via Context7.", + model: "anthropic/claude-sonnet-4-6", + tools: await context7.listTools(), + }); + ``` + + + +## How It Works + +Once connected, your Mastra agents will query Context7 for relevant library documentation. This helps agents: + +- Answer technical questions with accurate, up-to-date API references +- Generate code that follows current library patterns and best practices +- Avoid hallucinating outdated or incorrect API usage +- Provide version-specific guidance for any supported library diff --git a/docs/integrations/tembo.mdx b/docs/integrations/tembo.mdx new file mode 100644 index 0000000..c8481a9 --- /dev/null +++ b/docs/integrations/tembo.mdx @@ -0,0 +1,36 @@ +--- +title: Tembo +sidebarTitle: Tembo +description: Orchestration layer for AI-powered engineering workflows +--- + +[Tembo](https://tembo.io) is a platform for orchestrating AI coding agents across repositories and integrations. Context7 is available as a built-in MCP integration in Tembo, giving agents access to up-to-date library documentation. + +For more details on how Tembo handles MCP, see the [Tembo MCP documentation](https://docs.tembo.io/integrations/mcp). + +## Setup + + + + Go to the **Integrations** page in your Tembo dashboard. You'll see Context7 listed under **MCP Servers**. + + ![Integrations page](/images/integrations/tembo/integrations-page.png) + + + Click the **Install** button on the **Context7** card. + + + After installation, Context7 will appear under your **Installed** integrations. + + ![Server connected](/images/integrations/tembo/server-connected.png) + + + +## How It Works + +Once connected, Tembo agents will query Context7 for relevant library documentation during tasks. This helps agents: + +- Generate correct implementations based on the latest API references +- Identify deprecated patterns during automated code reviews +- Produce PRs that follow current library best practices +- Reduce back-and-forth by getting it right the first time diff --git a/docs/library-owners.mdx b/docs/library-owners.mdx new file mode 100644 index 0000000..b6d9467 --- /dev/null +++ b/docs/library-owners.mdx @@ -0,0 +1,147 @@ +--- +title: Library Owners +description: Claim your library and control how Context7 parses it with context7.json +--- + +If you maintain a library or framework, Context7 lets you control how its documentation is parsed and presented — so developers always receive current, trustworthy docs inside their coding environment. + +To simply add a public library, see [Adding Libraries](/adding-libraries). This page covers ownership and advanced configuration. + +## Claiming Your Library + +If you're the library owner, you can claim your library on Context7 to unlock a web-based admin panel for managing configuration. This allows you to: + +- Edit settings through a user interface instead of committing file changes +- Invite team members to collaborate on configuration +- Add and manage multiple versions of your library documentation +- Get higher rate limits for refresh operations + +**[Learn more about claiming libraries →](/howto/claiming-libraries)** + +## Who Can Manage Configuration? + +- **Library authors**: Claim ownership via `context7.json` and manage settings through the admin panel, or add configuration directly to your repository +- **Contributors**: Submit pull requests to add or update the configuration + +## Advanced Configuration with `context7.json` + +For more control over how Context7 parses and presents your library, you can add a `context7.json` file to the root of your repository. This file works similarly to `robots.txt` and tells Context7 how to handle your project. + +`context7.json` controls *where* Context7 looks, not *what kind* of files it reads — see [What Gets Indexed](/adding-libraries#what-gets-indexed) for the parsed file types and the source-code fallback for repositories without documentation. + +### Configuration Fields + +Here's an example `context7.json` file with all available options: + +```json +{ + "$schema": "https://context7.com/schema/context7.json", + "projectTitle": "Upstash Ratelimit", + "description": "Ratelimiting library based on Upstash Redis", + "folders": [], + "excludeFolders": ["src"], + "excludeFiles": [], + "rules": ["Use Upstash Redis as a database", "Use single region set up"], + "previousVersions": [ + { + "tag": "v1.2.1" + } + ] +} +``` + + + **Pro Tip**: Including the `$schema` field enables autocomplete, validation, and helpful tooltips + in modern code editors like VS Code, making it easier to create and maintain your configuration. + + +## Field Descriptions + +- **`projectTitle`** (string): Suggested display name for your project in Context7. Only used when the LLM cannot generate a name with high confidence. + +- **`description`** (string): Suggested description for your project in Context7. Only used when the LLM cannot generate a description with high confidence. + +- **`branch`** (string): The name of the git branch to parse. If not provided, the default branch will be used. + +- **`folders`** (array): Specific folder paths to include when parsing. If empty, Context7 scans the entire repository. Root-level markdown files are always included. + +- **`excludeFolders`** (array): Patterns to exclude from documentation parsing. Supports simple names, paths, and glob patterns (see Exclusion Patterns below). + +- **`excludeFiles`** (array): Specific file names to exclude. Use only the filename, not the full path. Examples: `CHANGELOG.md`, license files, or non-documentation content. + +- **`rules`** (array): Best practices or important guidelines that coding agents should follow when using your library. These appear as recommendations in the documentation context provided to coding agents. + +- **`previousVersions`** (array): Information about previous versions of your library that should also be available in Context7. + - **`tag`**: The Git tag or version identifier + +- **`branchVersions`** (array): Information about previous versions (branch-based) of your library that should also + be available in Context7. + - **`branch`**: The Git branch + +### How `folders` and `excludeFolders` interact + +`excludeFolders` always takes priority over `folders`. Evaluation order for any given file: + +1. Does the file's path (or any ancestor directory) match an `excludeFolders` pattern? → **excluded**, stop. +2. Is `folders` non-empty and the file is not under any listed folder? → **excluded**, stop. +3. Otherwise → **included**. + +**Example — scan selected directories but skip archived content:** + +```json +{ + "folders": ["docs", "api-reference"], + "excludeFolders": ["docs/archive", "**/old"] +} +``` + +This scans only `docs/` and `api-reference/`, but within those it skips `docs/archive/` and any folder named `old` at any depth. + +### Exclusion Patterns + +The `excludeFolders` parameter supports various pattern types for flexible exclusion: + +- **Simple folder names**: `"node_modules"` - Excludes any folder named "node_modules" anywhere in the tree +- **Root-specific patterns**: `"./xyz"` - Excludes the folder only at repository root (e.g., excludes `/xyz` but not `/dist/xyz`) +- **Path patterns**: `"app-sdk/v2.3"` - Excludes specific paths and everything under them +- **Glob patterns**: `"*.test"`, `"temp*"` - Excludes folders matching the pattern +- **Globstar patterns**: `"**/dist"`, `"docs/**/internal"` - Advanced path matching +- **Complex patterns**: `"src/**/*.test.js"` - Exclude test files in the src directory + +Examples: + +- `"node_modules"` - Excludes all node_modules folders anywhere +- `"./build"` - Excludes the build folder only at root (not `src/build`) +- `"app-sdk/v2.3"` - Excludes the app-sdk/v2.3 path and all its contents +- `"*.test"` - Excludes folders ending with .test +- `"docs/**/internal"` - Excludes any "internal" folder under docs +- `"**/temp"` - Excludes any folder named "temp" anywhere + +### Default Exclusions + +If you don't specify `excludeFiles` or `excludeFolders` in your `context7.json` file, Context7 uses these default patterns: + +#### Default Excluded Files + +``` +CHANGELOG.md, changelog.md, CHANGELOG.mdx, changelog.mdx +LICENSE.md, license.md +CODE_OF_CONDUCT.md, code_of_conduct.md +``` + +#### Default Excluded Folders + +``` +*archive*, *archived*, old, docs/old, *deprecated*, *legacy* +*previous*, *outdated*, *superseded* +i18n/zh*, i18n/es*, i18n/fr*, i18n/de*, i18n/ja*, i18n/ko* +i18n/ru*, i18n/pt*, i18n/it*, i18n/ar*, i18n/hi*, i18n/tr* +i18n/nl*, i18n/pl*, i18n/sv*, i18n/vi*, i18n/th* +zh-cn, zh-tw, zh-hk, zh-mo, zh-sg +``` + +These defaults help coding agents avoid irrelevant, outdated, and non-technical content. + +## Need Help? + +If you encounter issues or need assistance adding your project, please [open an issue](https://github.com/upstash/context7/issues/new/choose) or reach out to our community. diff --git a/docs/library-updates.mdx b/docs/library-updates.mdx new file mode 100644 index 0000000..30691b8 --- /dev/null +++ b/docs/library-updates.mdx @@ -0,0 +1,60 @@ +--- +title: Keeping Libraries Fresh +description: How Context7 ensures library documentation stays fresh +--- + +Context7 automatically refreshes library documentation so that developers always receive accurate, up-to-date context in their coding environment. Here's how it works. + +## Automatic Refresh + +Every time a library is requested through Context7 — whether via the MCP server or the REST API — the system checks when the documentation was last updated. If it's older than a threshold based on the library's popularity, a background refresh is triggered automatically. + +### Refresh Thresholds + +The staleness threshold is based on each library's popularity rank in Context7: + +| Popularity Rank | Refresh Threshold | +| --------------- | ----------------- | +| Top 100 | 1 day | +| Top 1,000 | 15 days | +| Top 5,000 | 30 days | +| All others | 45 days | + +Popular libraries are refreshed more frequently because developers rely on them more heavily and they tend to get updated faster. Website libraries use a slightly higher threshold than the values above. + + + The refresh is triggered in the background and does not affect the response time of your current request. You will receive the existing documentation immediately while the update runs asynchronously. + + +## Manual Refresh + +Logged-in users can manually trigger a refresh for any library directly from the library page on Context7 or via the [refresh API endpoint](/api-reference/refresh/refresh-a-library). This is useful when you know a library has just released a new version and want the updated documentation immediately, without waiting for the automatic cycle to complete. + +Library owners who have [claimed their library](/howto/claiming-libraries) receive higher refresh rate limits, giving them more control over how frequently their documentation can be updated. + +## What Triggers an Automated Refresh + +A refresh is triggered when all of the following conditions are met: + +- The library has been requested recently +- The documentation is older than the threshold for that library's popularity rank + +If a library hasn't been requested recently, it won't be refreshed — keeping the system efficient and focused on actively used documentation. + + + Private libraries are not refreshed automatically. To update a private library's documentation, trigger a manual refresh from the library page. + + +## Supported Library Types + +Automatic and manual refreshes work across all supported source types: + +- **Git repositories** — re-parsed from the configured branch +- **Websites** — re-crawled from the base URL +- **OpenAPI specs** — re-fetched and re-indexed from the spec source + +## Related + +- [Adding Libraries](/adding-libraries) +- [Claim Your Library](/howto/claiming-libraries) +- [Managing Versions](/howto/claiming-libraries#managing-versions) diff --git a/docs/openapi-enterprise.json b/docs/openapi-enterprise.json new file mode 100644 index 0000000..0c1d116 --- /dev/null +++ b/docs/openapi-enterprise.json @@ -0,0 +1,926 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Context7 On-Premise API", + "description": "REST API for the Context7 On-Premise server. Covers library parsing and documentation search.", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://your-instance.example.com/api", + "description": "Your on-premise deployment (replace with your actual host)" + }, + { + "url": "http://localhost:3000/api", + "description": "Local development" + } + ], + "paths": { + "/v2/libs/search": { + "get": { + "summary": "Search for libraries", + "description": "Search locally indexed libraries by name. Results may also include public libraries from Context7 Cloud depending on your policy settings.", + "operationId": "searchLibraries", + "tags": ["Search"], + "parameters": [ + { + "name": "libraryName", + "in": "query", + "description": "Library name to search for (e.g., `react`, `nextjs`)", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "example": "react" + }, + { + "name": "query", + "in": "query", + "description": "User's original question or task - used for relevance ranking", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "example": "How to manage state with hooks" + } + ], + "responses": { + "200": { + "description": "Search results ranked by relevance", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchResponse" + }, + "example": { + "results": [ + { + "id": "/your-org/your-repo", + "title": "Your Repo", + "description": "Internal tooling docs", + "totalSnippets": 150, + "source": "Local (Private)", + "trustScore": 10 + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + {}, + { "bearerAuth": [] } + ] + } + }, + "/v2/context": { + "get": { + "summary": "Get documentation context", + "description": "Retrieve documentation snippets for a library ranked by relevance to your query, formatted as plain text ready to inject into an LLM prompt. This is the endpoint MCP tools call internally.", + "operationId": "getContext", + "tags": ["Context"], + "parameters": [ + { + "name": "libraryId", + "in": "query", + "description": "Library ID returned by `GET /v2/libs/search` (e.g., `/your-org/your-repo`)", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "example": "/vercel/next.js" + }, + { + "name": "query", + "in": "query", + "description": "Natural language question or topic to retrieve context for", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "example": "How do I use the app router?" + } + ], + "responses": { + "200": { + "description": "Relevant documentation snippets as plain text", + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "### useRouter()\n\nSource: https://github.com/vercel/next.js/...\n\nThe `useRouter` hook allows you to programmatically change routes inside Client Components.\n\n--------------------------------\n\n### app/layout.tsx\n\n```tsx\nexport default function Layout({ children }) {\n return {children}\n}\n```" + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + {}, + { "bearerAuth": [] } + ] + } + }, + "/parse": { + "post": { + "summary": "Parse a Git repository", + "description": "Queue a GitHub or GitLab repository for parsing and indexing. Returns immediately with a queue position. Monitor progress with `GET /parse-status`.", + "operationId": "parseRepo", + "tags": ["Parse"], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParseRepoRequest" + }, + "examples": { + "minimal": { + "summary": "Minimal - index the whole repo", + "value": { + "repoUrl": "https://github.com/your-org/your-repo" + } + }, + "withOptions": { + "summary": "With folder and branch filters", + "value": { + "repoUrl": "https://github.com/your-org/your-repo", + "branch": "main", + "folders": ["docs"], + "excludeFolders": ["node_modules"], + "force": false + } + } + } + } + } + }, + "responses": { + "202": { + "$ref": "#/components/responses/ParseQueued" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + {}, + { "bearerAuth": [] } + ] + } + }, + "/parse-openapi": { + "post": { + "summary": "Parse an OpenAPI spec by URL", + "description": "Queue a remote OpenAPI specification (JSON or YAML) for parsing and indexing.", + "operationId": "parseOpenApi", + "tags": ["Parse"], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["openApiUrl"], + "properties": { + "openApiUrl": { + "type": "string", + "format": "uri", + "description": "URL of a JSON or YAML OpenAPI specification" + }, + "projectTitle": { + "type": "string", + "description": "Display name for the project" + }, + "description": { + "type": "string", + "description": "Short description shown in the library list" + }, + "force": { + "type": "boolean", + "description": "Re-parse even if already indexed", + "default": false + } + } + }, + "example": { + "openApiUrl": "https://example.com/openapi.json", + "projectTitle": "My API" + } + } + } + }, + "responses": { + "202": { + "$ref": "#/components/responses/ParseQueued" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + {}, + { "bearerAuth": [] } + ] + } + }, + "/parse-openapi-upload": { + "post": { + "summary": "Upload an OpenAPI spec file", + "description": "Upload an OpenAPI specification file directly for parsing and indexing.", + "operationId": "parseOpenApiUpload", + "tags": ["Parse"], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": ["openapiFile"], + "properties": { + "openapiFile": { + "type": "string", + "format": "binary", + "description": "A `.json` or `.yaml` OpenAPI specification file" + } + } + } + } + } + }, + "responses": { + "202": { + "$ref": "#/components/responses/ParseQueued" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + {}, + { "bearerAuth": [] } + ] + } + }, + "/import-libraries": { + "post": { + "summary": "Import a library bundle", + "description": "Import pre-parsed libraries into an airgapped on-premise install. Accepts either a Context7 Cloud export `.zip` (`multipart/form-data`) or a JSON body (`application/json`) for programmatic clients. Requires a personal API key (or an admin session). Each library is queued as its own job and its snippets are re-embedded locally with this install's configured provider. Available only on installs running an **offline (airgapped) license**.", + "operationId": "importLibraries", + "tags": ["Parse"], + "parameters": [ + { + "name": "force", + "in": "query", + "required": false, + "schema": { "type": "boolean", "default": false }, + "description": "Overwrite libraries that already exist. Handy when posting a piped export body, which carries no `force` field. Without it, existing libraries are skipped." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportLibrariesRequest" + } + }, + "multipart/form-data": { + "schema": { + "type": "object", + "required": ["bundleFile"], + "properties": { + "bundleFile": { + "type": "string", + "format": "binary", + "description": "A Context7 Cloud `context7-libraries.zip` export (up to 100 MB)" + }, + "force": { + "type": "boolean", + "description": "Overwrite libraries that already exist on this install", + "default": false + } + } + } + } + } + }, + "responses": { + "202": { + "$ref": "#/components/responses/LibrariesImported" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [{ "bearerAuth": [] }] + } + }, + "/parse-website": { + "post": { + "summary": "Parse a website", + "description": "Crawl and index a public website starting from the given URL.", + "operationId": "parseWebsite", + "tags": ["Parse"], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["websiteUrl"], + "properties": { + "websiteUrl": { + "type": "string", + "format": "uri", + "description": "Root URL to start crawling from" + }, + "projectTitle": { + "type": "string", + "description": "Display name for the project" + }, + "description": { + "type": "string", + "description": "Short description shown in the library list" + }, + "maxPages": { + "type": "integer", + "description": "Maximum number of pages to crawl", + "default": 100 + }, + "maxDepth": { + "type": "integer", + "description": "Maximum link depth from the root URL", + "default": 3 + }, + "excludePatterns": { + "type": "array", + "items": { "type": "string" }, + "description": "URL path patterns to skip (e.g., `/blog/*`)" + }, + "force": { + "type": "boolean", + "description": "Re-crawl even if already indexed", + "default": false + } + } + }, + "example": { + "websiteUrl": "https://docs.example.com", + "maxPages": 50 + } + } + } + }, + "responses": { + "202": { + "$ref": "#/components/responses/ParseQueued" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + {}, + { "bearerAuth": [] } + ] + } + }, + "/projects/{projectId}/refresh": { + "post": { + "summary": "Refresh a library", + "description": "Re-parse an existing library using its stored settings. Returns immediately with a queue position.\n\nNot available for:\n- Libraries imported from Context7 Cloud (re-import an updated bundle instead)\n- Uploaded OpenAPI files (re-upload the file instead)", + "operationId": "refreshProject", + "tags": ["Parse"], + "parameters": [ + { + "name": "projectId", + "in": "path", + "required": true, + "description": "Project identifier without the leading slash. For repositories use `owner/repo` (e.g. `upstash/ratelimit-js`). For websites use `websites/hostname` (e.g. `websites/upstash`). For OpenAPI specs use `openapi/derived-name`.", + "schema": { + "type": "string" + }, + "example": "upstash/ratelimit-js" + } + ], + "responses": { + "202": { + "$ref": "#/components/responses/ParseQueued" + }, + "400": { + "description": "Bad Request - refresh not available for this project type", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" }, + "examples": { + "imported": { + "summary": "Imported library", + "value": { "error": "Refresh isn't available for imported libraries. Re-import an updated export from Context7 Cloud to update it." } + }, + "uploadedFile": { + "summary": "Uploaded OpenAPI file", + "value": { "error": "Refresh not available for uploaded OpenAPI files. Re-upload the same file to update." } + }, + "noToken": { + "summary": "No git token configured", + "value": { "error": "No git token configured for GitHub. Configure a GitHub App or set a personal access token." } + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "409": { + "description": "Conflict - a parse job is already active or queued for this project", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" }, + "example": { "error": "This project is already queued", "project": "/upstash/ratelimit-js", "status": "queued" } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + {}, + { "bearerAuth": [] } + ] + } + }, + "/parse-status": { + "get": { + "summary": "Get parse status", + "description": "Returns the current status of all active and queued parse jobs.", + "operationId": "getParseStatus", + "tags": ["Parse"], + "responses": { + "200": { + "description": "Active parse jobs and their status", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParseStatusResponse" + }, + "example": { + "activeParses": { + "/your-org/your-repo": { + "status": "parsing", + "startedAt": "2025-01-01T12:00:00.000Z", + "duration": 8.6, + "statusMessage": "Scanning 16 files" + }, + "/other-org/other-repo": { + "status": "queued", + "position": 1, + "createdAt": "2025-01-01T12:00:01.000Z" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + {}, + { "bearerAuth": [] } + ] + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "description": "API key generated from Personal Settings. See [Authentication](/enterprise/api/authentication#creating-an-api-key)." + } + }, + "schemas": { + "Library": { + "type": "object", + "description": "An indexed library", + "properties": { + "id": { + "type": "string", + "description": "Library ID to pass to `GET /v2/context`", + "example": "/your-org/your-repo" + }, + "title": { + "type": "string", + "description": "Display name", + "example": "Your Repo" + }, + "description": { + "type": "string", + "description": "Short description", + "example": "Internal tooling docs" + }, + "totalSnippets": { + "type": "integer", + "description": "Number of indexed snippets", + "example": 150 + }, + "source": { + "type": "string", + "description": "Where the library was indexed from", + "example": "Local (Private)" + }, + "trustScore": { + "type": "integer", + "description": "Source reputation score (0–10)", + "example": 10 + } + } + }, + "SearchResponse": { + "type": "object", + "properties": { + "results": { + "type": "array", + "description": "Matching libraries ranked by relevance", + "items": { + "$ref": "#/components/schemas/Library" + } + } + }, + "required": ["results"] + }, + "ParseQueuedResponse": { + "type": "object", + "properties": { + "message": { + "type": "string", + "example": "Parse queued" + }, + "project": { + "type": "string", + "description": "Project identifier assigned to this library (e.g. `/your-org/your-repo`)", + "example": "/your-org/your-repo" + }, + "queueId": { + "type": "integer", + "description": "Numeric ID for this parse job", + "example": 5 + }, + "position": { + "type": "integer", + "nullable": true, + "description": "Position in the queue. `null` if the job started immediately", + "example": 1 + } + }, + "required": ["message", "project", "queueId"] + }, + "ImportLibrariesRequest": { + "type": "object", + "required": ["libraries"], + "properties": { + "libraries": { + "type": "array", + "description": "The libraries to import. Each carries its full snippet content; embeddings are recomputed on this install.", + "items": { + "$ref": "#/components/schemas/ImportLibrary" + } + }, + "force": { + "type": "boolean", + "description": "Overwrite libraries that already exist on this install", + "default": false + } + } + }, + "ImportLibrary": { + "type": "object", + "required": ["project", "codeSnippets", "infoSnippets"], + "properties": { + "project": { + "type": "string", + "description": "Library identifier, e.g. `/your-org/your-repo`", + "example": "/vercel/next.js" + }, + "title": { "type": "string" }, + "description": { "type": "string" }, + "type": { + "type": "string", + "description": "Source type of the library (e.g. `repo`, `website`, `openapi`)" + }, + "language": { "type": "string", "example": "English" }, + "branch": { "type": "string" }, + "docsRepoUrl": { "type": "string" }, + "docsSiteUrl": { "type": "string" }, + "totalTokens": { "type": "integer" }, + "codeSnippets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { "type": "string" }, + "title": { "type": "string" }, + "description": { "type": "string" }, + "language": { "type": "string" }, + "codeList": { + "type": "array", + "items": { + "type": "object", + "properties": { + "language": { "type": "string" }, + "code": { "type": "string" } + } + } + }, + "tokens": { "type": "integer" } + } + } + }, + "infoSnippets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { "type": "string" }, + "content": { "type": "string" }, + "breadcrumb": { "type": "string" }, + "tokens": { "type": "integer" } + } + } + } + } + }, + "LibrariesImportedResponse": { + "type": "object", + "properties": { + "message": { + "type": "string", + "example": "Queued 2 libraries for import" + }, + "queued": { + "type": "array", + "description": "Library identifiers queued for import", + "items": { "type": "string" }, + "example": ["/vercel/next.js", "/facebook/react"] + }, + "skipped": { + "type": "array", + "description": "Libraries that were not imported, with a reason", + "items": { + "type": "object", + "properties": { + "project": { "type": "string" }, + "reason": { + "type": "string", + "example": "already exists" + } + } + } + } + }, + "required": ["message", "queued", "skipped"] + }, + "ParseRepoRequest": { + "type": "object", + "required": ["repoUrl"], + "properties": { + "repoUrl": { + "type": "string", + "format": "uri", + "description": "HTTPS URL of the GitHub or GitLab repository" + }, + "branch": { + "type": "string", + "description": "Branch to parse. Defaults to the repository's default branch" + }, + "folders": { + "type": "array", + "items": { "type": "string" }, + "description": "Only index files under these paths. Empty means the entire repository" + }, + "excludeFolders": { + "type": "array", + "items": { "type": "string" }, + "description": "Paths to skip during indexing" + }, + "excludeFiles": { + "type": "array", + "items": { "type": "string" }, + "description": "Glob patterns for files to exclude" + }, + "force": { + "type": "boolean", + "description": "Re-parse even if the current commit is already indexed", + "default": false + } + } + }, + "ParseJobStatus": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": ["queued", "parsing", "finalizing"], + "description": "Current job status" + }, + "position": { + "type": "integer", + "description": "Queue position. Only present when `status` is `queued`" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp when the job was queued. Only present when `status` is `queued`" + }, + "startedAt": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp when the job began running. Only present when `status` is `parsing` or `finalizing`" + }, + "duration": { + "type": "number", + "description": "Elapsed seconds since the job started. Only present when `status` is `parsing` or `finalizing`" + }, + "statusMessage": { + "type": "string", + "description": "Human-readable progress detail (e.g. `Scanning 16 files`). Only present when `status` is `parsing`" + } + }, + "required": ["status"] + }, + "ParseStatusResponse": { + "type": "object", + "properties": { + "activeParses": { + "type": "object", + "description": "Map of project name to its current parse job status", + "additionalProperties": { + "$ref": "#/components/schemas/ParseJobStatus" + } + } + }, + "required": ["activeParses"] + }, + "Error": { + "type": "object", + "properties": { + "error": { + "type": "string", + "description": "Human-readable error description" + } + }, + "required": ["error"] + } + }, + "responses": { + "ParseQueued": { + "description": "Parse job accepted and queued", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParseQueuedResponse" + } + } + } + }, + "LibrariesImported": { + "description": "Libraries accepted and queued for import", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LibrariesImportedResponse" + } + } + } + }, + "ForbiddenError": { + "description": "Forbidden - the action is not permitted for this install or user", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" }, + "example": { "error": "Library import is available only with an offline license." } + } + } + }, + "BadRequestError": { + "description": "Bad Request - invalid or missing parameters", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" }, + "example": { "error": "repoUrl is required" } + } + } + }, + "UnauthorizedError": { + "description": "Unauthorized - authentication required", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" }, + "example": { "error": "Authentication required" } + } + } + }, + "NotFoundError": { + "description": "Not Found - library does not exist", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" }, + "example": { "error": "Project not found" } + } + } + }, + "InternalServerError": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" }, + "example": { "error": "An unexpected error occurred" } + } + } + } + } + }, + "tags": [ + { + "name": "Search", + "description": "Search indexed libraries" + }, + { + "name": "Context", + "description": "Retrieve documentation context for queries" + }, + { + "name": "Parse", + "description": "Parse and index new libraries" + } + ] +} diff --git a/docs/openapi.json b/docs/openapi.json new file mode 100644 index 0000000..68f1f10 --- /dev/null +++ b/docs/openapi.json @@ -0,0 +1,2795 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Context7 Public API", + "description": "The Context7 Public API provides programmatic access to library documentation and search functionality. Get up-to-date documentation and code examples for any library.", + "version": "2.0.0", + "contact": { + "name": "Context7 Support", + "url": "https://context7.com", + "email": "support@context7.com" + } + }, + "servers": [ + { + "url": "https://context7.com/api", + "description": "Production server" + } + ], + "paths": { + "/v2/libs/search": { + "get": { + "summary": "Search for libraries", + "description": "Search for libraries by name with intelligent LLM-powered ranking based on your query context.", + "operationId": "searchLibraries", + "tags": [ + "Search" + ], + "parameters": [ + { + "$ref": "#/components/parameters/LibraryNameParam" + }, + { + "$ref": "#/components/parameters/QueryParam" + }, + { + "$ref": "#/components/parameters/FastParam" + } + ], + "responses": { + "200": { + "description": "Search results ranked by relevance", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchResponse" + }, + "example": { + "results": [ + { + "id": "/facebook/react", + "title": "React", + "description": "A JavaScript library for building user interfaces", + "branch": "main", + "lastUpdateDate": "2025-01-15T10:30:00.000Z", + "state": "finalized", + "totalTokens": 500000, + "totalSnippets": 2500, + "stars": 220000, + "trustScore": 10, + "benchmarkScore": 95.5, + "versions": [ + "v18.2.0", + "v17.0.2" + ] + } + ], + "searchFilterApplied": false + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "402": { + "$ref": "#/components/responses/SpendingLimitError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailableError" + } + }, + "security": [ + {}, + { + "bearerAuth": [] + } + ] + } + }, + "/v2/libs/metrics": { + "get": { + "summary": "Get library usage metrics", + "description": "Retrieve full usage metrics for a library: cumulative and daily request counters broken down by surface (web page, text docs, MCP, CLI), MCP client daily unique-user breakdown, and lifetime topic and country distributions. The API key must belong to a member of the teamspace that owns the library — claim ownership from the library's admin page on context7.com.", + "operationId": "getLibraryMetrics", + "tags": [ + "Metrics" + ], + "parameters": [ + { + "$ref": "#/components/parameters/LibraryIdParam" + }, + { + "$ref": "#/components/parameters/DaysParam" + } + ], + "responses": { + "200": { + "description": "Library usage metrics", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LibraryMetricsResponse" + }, + "example": { + "total": { + "page": 12450, + "txt": 3820, + "mcp": 95210, + "cli": 1240 + }, + "daily": [ + { + "date": "2025-01-14", + "page": 8, + "txt": 3, + "mcp": 42, + "cli": 1, + "total": 54 + }, + { + "date": "2025-01-15", + "page": 11, + "txt": 5, + "mcp": 67, + "cli": 0, + "total": 83 + } + ], + "mcpClients": { + "dailyData": [ + { + "date": "2025-01-14", + "uniqueUsersByClient": { + "cursor": 12, + "claude-code": 7 + }, + "totalUniqueUsers": 18 + }, + { + "date": "2025-01-15", + "uniqueUsersByClient": { + "cursor": 15, + "claude-code": 9, + "codex": 2 + }, + "totalUniqueUsers": 25 + } + ] + }, + "topics": [ + { "topic": "routing", "count": 420 }, + { "topic": "middleware", "count": 312 }, + { "topic": "app-router", "count": 187 } + ], + "countries": [ + { "country": "US", "count": 3120 }, + { "country": "DE", "count": 842 }, + { "country": "IN", "count": 610 } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/context": { + "get": { + "summary": "Get documentation context", + "description": "Retrieve intelligent, LLM-reranked documentation context for natural language queries. Returns the most relevant code snippets and documentation for your specific question.", + "operationId": "getContext", + "tags": [ + "Context" + ], + "parameters": [ + { + "$ref": "#/components/parameters/LibraryIdParam" + }, + { + "$ref": "#/components/parameters/QueryParam" + }, + { + "$ref": "#/components/parameters/TypeParam" + }, + { + "$ref": "#/components/parameters/FastParam" + } + ], + "responses": { + "200": { + "description": "Documentation context", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextResponse" + }, + "example": { + "codeSnippets": [ + { + "codeTitle": "Middleware Authentication Example", + "codeDescription": "Shows how to implement authentication checks in Next.js middleware", + "codeLanguage": "typescript", + "codeTokens": 150, + "codeId": "https://github.com/vercel/next.js/blob/canary/docs/middleware.mdx#_snippet_0", + "pageTitle": "Middleware", + "codeList": [ + { + "language": "typescript", + "code": "import { NextResponse } from 'next/server'\nimport type { NextRequest } from 'next/server'\n\nexport function middleware(request: NextRequest) {\n const token = request.cookies.get('token')\n if (!token) {\n return NextResponse.redirect(new URL('/login', request.url))\n }\n return NextResponse.next()\n}" + } + ] + } + ], + "infoSnippets": [ + { + "pageId": "https://github.com/vercel/next.js/blob/canary/docs/middleware.mdx", + "breadcrumb": "Routing > Middleware", + "content": "Middleware allows you to run code before a request is completed...", + "contentTokens": 200 + } + ] + } + }, + "text/plain": { + "schema": { + "type": "string" + }, + "example": "### Middleware Authentication Example\n\nSource: https://github.com/vercel/next.js/blob/canary/docs/middleware.mdx\n\nShows how to implement authentication checks in Next.js middleware\n\n```typescript\nimport { NextResponse } from 'next/server'\n...\n```" + } + } + }, + "202": { + "$ref": "#/components/responses/AcceptedError" + }, + "301": { + "$ref": "#/components/responses/RedirectError" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "402": { + "$ref": "#/components/responses/SpendingLimitError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + {}, + { + "bearerAuth": [] + } + ] + } + }, + "/v1/refresh": { + "post": { + "summary": "Refresh a library", + "description": "Trigger a refresh of an existing library to fetch the latest documentation. Library owners have dedicated refresh limits.", + "operationId": "refreshLibrary", + "tags": [ + "Refresh" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "libraryName" + ], + "properties": { + "libraryName": { + "type": "string", + "description": "Library identifier — the URL path of the library on context7.com. Use `/owner/repo` for GitHub repositories (e.g., `/vercel/next.js`), or `//` for other sources (e.g., `/websites/uploadcare_com`, `/llmstxt/`). See [Library ID format](/api-guide#library-id-format)." + }, + "branch": { + "type": "string", + "description": "Optional branch name to refresh" + }, + "gitToken": { + "type": "string", + "description": "Optional Git access token for refreshing private repositories. If not provided, the stored OAuth token will be used." + } + } + }, + "examples": { + "github": { + "summary": "GitHub repository", + "value": { "libraryName": "/vercel/next.js" } + }, + "website": { + "summary": "Website source", + "value": { "libraryName": "/websites/uploadcare_com" } + }, + "llmstxt": { + "summary": "llms.txt source", + "value": { "libraryName": "/llmstxt/example" } + } + } + } + } + }, + "responses": { + "200": { + "description": "Refresh started successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + }, + "required": [ + "message" + ] + }, + "example": { + "message": "Refresh started successfully" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/policies": { + "get": { + "summary": "Get teamspace policies", + "description": "Retrieve the current policy configuration for the teamspace associated with the API key. Includes source type access settings and public repository filters.", + "operationId": "getPolicies", + "tags": [ + "Policies" + ], + "responses": { + "200": { + "description": "Current policy configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PolicyResponse" + }, + "example": { + "sourceTypes": { + "public_repos": { + "enabled": true + }, + "private_sources": { + "enabled": true + }, + "confluence": { + "enabled": false + }, + "uploaded_files": { + "enabled": true + }, + "websites": { + "enabled": true + }, + "llmstxt": { + "enabled": true + } + }, + "libraryFilters": { + "mode": "quality", + "quality": { + "requireVerified": false, + "minTrustScore": null, + "maxAgeDays": 365, + "blockedLibraries": [ + "/org/repo", + "example.com" + ], + "exceptedLibraries": [ + "/vercel/next.js" + ], + "repoFilters": { + "minStars": 100, + "allowedLicenses": [ + "MIT", + "Apache-2.0" + ] + } + }, + "select": { + "allowedLibraries": [] + } + }, + "accessibleLibraryCount": 4521 + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + }, + "patch": { + "summary": "Update teamspace policies", + "description": "Incrementally update policy configuration for the teamspace associated with the API key. Only the fields you include in the request body are modified — omitted fields remain unchanged. For source types, use `enable`/`disable` arrays (both allowed if no overlap). For library lists, use `add`/`remove` objects or `clear: true` to remove all. Requires owner or admin role. All field names use camelCase.", + "operationId": "updatePolicies", + "tags": [ + "Policies" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PatchPoliciesRequest" + }, + "examples": { + "disableSourceType": { + "summary": "Disable a source type", + "value": { + "sourceTypes": { + "disable": [ + "websites" + ] + } + } + }, + "setQualityFilters": { + "summary": "Set quality filter thresholds", + "value": { + "libraryFilters": { + "quality": { + "requireVerified": true, + "minTrustScore": 4, + "repoFilters": { + "minStars": 1000 + } + } + } + } + }, + "setWebsiteFilters": { + "summary": "Set website quality filters", + "value": { + "libraryFilters": { + "quality": { + "websiteFilters": { + "minBacklinks": 100, + "minReferringDomains": 10, + "minOrganicTraffic": 1000 + } + } + } + } + }, + "blockLibrary": { + "summary": "Add a library to the blocked list", + "value": { + "libraryFilters": { + "quality": { + "blockedLibraries": { + "add": [ + "/org/repo" + ] + } + } + } + } + }, + "blockDomain": { + "summary": "Block all libraries from a domain", + "value": { + "libraryFilters": { + "quality": { + "blockedLibraries": { + "add": [ + "example.com" + ] + } + } + } + } + }, + "exceptLibrary": { + "summary": "Add a library exception (bypasses all filters)", + "value": { + "libraryFilters": { + "quality": { + "exceptedLibraries": { + "add": [ + "/vercel/next.js" + ] + } + } + } + } + }, + "allowPermissiveLicenses": { + "summary": "Restrict public repos to permissive SPDX licenses", + "value": { + "libraryFilters": { + "quality": { + "repoFilters": { + "allowedLicenses": { + "add": [ + "MIT", + "Apache-2.0", + "BSD-3-Clause", + "ISC" + ] + } + } + } + } + } + }, + "clearLicenseRestriction": { + "summary": "Remove all license restrictions", + "value": { + "libraryFilters": { + "quality": { + "repoFilters": { + "allowedLicenses": { + "clear": true + } + } + } + } + } + }, + "allowDomain": { + "summary": "Allow libraries from a specific domain (select mode)", + "value": { + "libraryFilters": { + "select": { + "allowedLibraries": { + "add": [ + "stripe.com", + "/vercel/next.js" + ] + } + } + } + } + }, + "clearAllowedLibraries": { + "summary": "Clear all allowed libraries", + "value": { + "libraryFilters": { + "select": { + "allowedLibraries": { + "clear": true + } + } + } + } + }, + "combined": { + "summary": "Multiple changes in one request", + "value": { + "sourceTypes": { + "enable": [ + "websites" + ], + "disable": [ + "confluence" + ] + }, + "libraryFilters": { + "mode": "quality", + "quality": { + "minTrustScore": 4, + "maxAgeDays": 365, + "blockedLibraries": { + "add": [ + "/org/repo" + ], + "remove": [ + "/org/old-repo" + ] + }, + "repoFilters": { + "minStars": 100 + }, + "websiteFilters": { + "minBacklinks": 100 + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Updated policy configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PolicyResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/repo/github": { + "post": { + "summary": "Add a GitHub repository", + "description": "Submit a GitHub repository for documentation processing. Supports private repos via a gitToken or by connecting your GitHub account at https://context7.com/add-library.", + "operationId": "addGitHubRepo", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddRepoRequest" + }, + "example": { + "docsRepoUrl": "https://github.com/vercel/next.js" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "409": { + "$ref": "#/components/responses/DuplicateError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/repo/gitlab": { + "post": { + "summary": "Add a GitLab repository", + "description": "Submit a GitLab repository for documentation processing. Supports private repos via a gitToken or by connecting your GitLab account at https://context7.com/add-library.", + "operationId": "addGitLabRepo", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddRepoRequest" + }, + "example": { + "docsRepoUrl": "https://gitlab.com/owner/repo" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "409": { + "$ref": "#/components/responses/DuplicateError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/repo/bitbucket": { + "post": { + "summary": "Add a Bitbucket repository", + "description": "Submit a Bitbucket repository for documentation processing. Supports private repos via a gitToken or by connecting your Bitbucket account at https://context7.com/add-library.", + "operationId": "addBitbucketRepo", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddRepoRequest" + }, + "example": { + "docsRepoUrl": "https://bitbucket.org/owner/repo" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "409": { + "$ref": "#/components/responses/DuplicateError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/repo/git": { + "post": { + "summary": "Add from other Git providers", + "description": "Submit a repository from any Git provider not covered by the dedicated GitHub, GitLab, or Bitbucket endpoints. Supports Gitea, Forgejo, Codeberg, self-hosted GitLab, and other Git servers. For private repos, provide a personal access token via the gitToken field.", + "operationId": "addGitRepo", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "docsRepoUrl" + ], + "properties": { + "docsRepoUrl": { + "type": "string", + "format": "uri", + "description": "The Git repository URL" + }, + "gitToken": { + "type": "string", + "description": "Personal access token for private repositories" + }, + "private": { + "type": "boolean", + "description": "Whether the repository is private" + }, + "skipVersionFiltering": { + "type": "boolean", + "description": "Skip filtering out version-specific documentation pages" + }, + "generateDocs": { + "type": "boolean", + "description": "Generate documentation from the repository source code. Applies to private repository submissions." + } + } + }, + "example": { + "docsRepoUrl": "https://codeberg.org/owner/repo" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "409": { + "$ref": "#/components/responses/DuplicateError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/openapi": { + "post": { + "summary": "Add an OpenAPI specification by URL", + "description": "Submit an OpenAPI specification URL for documentation processing.", + "operationId": "addOpenApi", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "openApiUrl" + ], + "properties": { + "openApiUrl": { + "type": "string", + "format": "uri", + "description": "URL pointing to an OpenAPI specification (JSON or YAML)" + } + } + }, + "example": { + "openApiUrl": "https://api.example.com/openapi.json" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/openapi-upload": { + "post": { + "summary": "Upload an OpenAPI specification file", + "description": "Upload an OpenAPI specification file (JSON or YAML) for documentation processing. Requires a team project. File size limit is 10MB.", + "operationId": "addOpenApiUpload", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "openapiFile" + ], + "properties": { + "openapiFile": { + "type": "string", + "format": "binary", + "description": "The OpenAPI specification file (.json, .yaml, or .yml)" + }, + "libraryTitle": { + "type": "string", + "description": "Custom title for the library" + }, + "description": { + "type": "string", + "description": "Description of the library" + }, + "force": { + "type": "string", + "enum": [ + "true" + ], + "description": "Set to 'true' to force reprocessing" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "409": { + "$ref": "#/components/responses/DuplicateError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/llmstxt": { + "post": { + "summary": "Add an llms.txt file", + "description": "Submit an llms.txt file URL for documentation processing.", + "operationId": "addLlmsTxt", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "llmstxtUrl" + ], + "properties": { + "llmstxtUrl": { + "type": "string", + "format": "uri", + "description": "URL pointing to an llms.txt, llms-full.txt, or llms-small.txt file" + } + } + }, + "example": { + "llmstxtUrl": "https://docs.example.com/llms.txt" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/website": { + "post": { + "summary": "Add a website", + "description": "Submit a website URL for documentation processing.", + "operationId": "addWebsite", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "websiteUrl" + ], + "properties": { + "websiteUrl": { + "type": "string", + "format": "uri", + "description": "The website URL to process" + }, + "websiteBaseUrl": { + "type": "string", + "format": "uri", + "description": "Base URL to limit crawling scope. Only pages starting with this URL will be indexed." + } + } + }, + "example": { + "websiteUrl": "https://docs.example.com" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/confluence": { + "post": { + "summary": "Add a Confluence space", + "description": "Submit a Confluence space for documentation processing. Requires a connected Confluence account and a team project. You can optionally specify specific page IDs to index only a subset of the space.", + "operationId": "addConfluence", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "cloudId", + "siteUrl", + "spaceKey", + "spaceName", + "title", + "description" + ], + "properties": { + "cloudId": { + "type": "string", + "description": "The Confluence cloud instance ID" + }, + "siteUrl": { + "type": "string", + "description": "The Confluence site URL" + }, + "spaceKey": { + "type": "string", + "description": "The Confluence space key" + }, + "spaceName": { + "type": "string", + "description": "The Confluence space name" + }, + "pageIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Optional list of specific page IDs to index. If omitted, the entire space is indexed." + }, + "title": { + "type": "string", + "description": "Title for the library" + }, + "description": { + "type": "string", + "description": "Description of the library" + }, + "projectId": { + "type": "string", + "description": "The team project ID to associate this Confluence space with" + } + } + }, + "example": { + "cloudId": "a]1b2c3d4-5e6f-7g8h-9i0j", + "siteUrl": "https://your-site.atlassian.net", + "spaceKey": "DOCS", + "spaceName": "Documentation", + "title": "My Docs", + "description": "Internal documentation", + "projectId": "project-uuid" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "409": { + "$ref": "#/components/responses/DuplicateError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/v2/add/notion": { + "post": { + "summary": "Add Notion pages", + "description": "Submit selected Notion pages for documentation processing. Requires a connected Notion account and a team project.", + "operationId": "addNotion", + "tags": [ + "Add Library" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "workspaceId", + "workspaceName", + "pageIds", + "title", + "description" + ], + "properties": { + "workspaceId": { + "type": "string", + "description": "The Notion workspace ID" + }, + "workspaceName": { + "type": "string", + "description": "The Notion workspace name" + }, + "pageIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of Notion page IDs to index." + }, + "title": { + "type": "string", + "description": "Title for the library" + }, + "description": { + "type": "string", + "description": "Description of the library" + }, + "projectId": { + "type": "string", + "description": "The team project ID to associate these Notion pages with" + } + } + }, + "example": { + "workspaceId": "workspace-uuid", + "workspaceName": "Acme Workspace", + "pageIds": [ + "page-1", + "page-2" + ], + "title": "Product Docs", + "description": "Internal Notion knowledge base", + "projectId": "project-uuid" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/AddLibrarySuccess" + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "409": { + "$ref": "#/components/responses/DuplicateError" + }, + "429": { + "$ref": "#/components/responses/RateLimitError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/GatewayTimeoutError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "description": "Get your API key at [context7.com/dashboard](https://context7.com/dashboard). Treat your API key like a password and store it securely." + } + }, + "parameters": { + "LibraryNameParam": { + "name": "libraryName", + "in": "query", + "description": "Library name to search for (e.g., 'react', 'nextjs', 'express')", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "example": "react" + }, + "QueryParam": { + "name": "query", + "in": "query", + "description": "User's original question or task - used for intelligent relevance ranking", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "example": "How to manage state with hooks" + }, + "LibraryIdParam": { + "name": "libraryId", + "in": "query", + "description": "Context7-compatible library ID — the URL path of the library on context7.com. Use `/owner/repo` for GitHub repositories, or `//` for other sources (websites, llms.txt, GitLab/Bitbucket, etc.). Optionally suffix with `/` or `@` to pin a specific version. See [Library ID format](/api-guide#library-id-format).", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 500, + "pattern": "^/[^/]+/[^/]+([/@][^/]+)?$" + }, + "examples": { + "github": { + "summary": "GitHub repository", + "value": "/vercel/next.js" + }, + "website": { + "summary": "Website source", + "value": "/websites/uploadcare_com" + }, + "llmstxt": { + "summary": "llms.txt source", + "value": "/llmstxt/example" + }, + "withVersion": { + "summary": "With specific version (slash)", + "value": "/vercel/next.js/v14.3.0" + }, + "withVersionAt": { + "summary": "With specific version (@ syntax)", + "value": "/vercel/next.js@v14.3.0" + } + } + }, + "TypeParam": { + "name": "type", + "in": "query", + "description": "Response format type", + "required": false, + "schema": { + "type": "string", + "enum": [ + "json", + "txt" + ], + "default": "txt" + }, + "example": "json" + }, + "FastParam": { + "name": "fast", + "in": "query", + "description": "When `true`, skip LLM reranking and return top vector-search results directly. Trades relevance quality for lower latency.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "true", + "false" + ], + "default": "false" + }, + "example": "true" + }, + "DaysParam": { + "name": "days", + "in": "query", + "description": "Number of days of daily history to return (1-365). Defaults to 30.", + "required": false, + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 365, + "default": 30 + }, + "example": 30 + } + }, + "schemas": { + "Library": { + "type": "object", + "description": "Library metadata", + "properties": { + "id": { + "type": "string", + "description": "Library ID — the URL path of the library on context7.com. `/owner/repo` for GitHub repositories, or `//` for other sources (e.g., `/vercel/next.js`, `/websites/uploadcare_com`). See [Library ID format](/api-guide#library-id-format).", + "example": "/vercel/next.js" + }, + "title": { + "type": "string", + "description": "Display name of the library", + "example": "Next.js" + }, + "description": { + "type": "string", + "description": "Short description", + "example": "The React Framework" + }, + "branch": { + "type": "string", + "description": "Git branch being tracked", + "example": "canary" + }, + "lastUpdateDate": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of last update", + "example": "2025-01-15T10:30:00.000Z" + }, + "state": { + "type": "string", + "enum": [ + "finalized", + "initial", + "processing", + "error", + "delete" + ], + "description": "Processing state of the library", + "example": "finalized" + }, + "totalTokens": { + "type": "integer", + "description": "Total tokens in documentation", + "example": 607822 + }, + "totalSnippets": { + "type": "integer", + "description": "Number of code snippets", + "example": 3629 + }, + "stars": { + "type": "integer", + "description": "GitHub stars count", + "example": 131745 + }, + "trustScore": { + "type": "integer", + "description": "Source reputation score (0-10)", + "minimum": 0, + "maximum": 10, + "example": 10 + }, + "benchmarkScore": { + "type": "number", + "description": "Quality indicator score (0-100)", + "minimum": 0, + "maximum": 100, + "example": 95.5 + }, + "versions": { + "type": "array", + "description": "Available version tags", + "items": { + "type": "string" + }, + "example": [ + "v15.1.8", + "v14.3.0" + ] + } + } + }, + "SearchResponse": { + "type": "object", + "description": "Search results response", + "properties": { + "results": { + "type": "array", + "description": "Array of matching libraries ranked by relevance", + "items": { + "$ref": "#/components/schemas/Library" + } + }, + "searchFilterApplied": { + "type": "boolean", + "description": "Indicates whether the search results were filtered by the teamspace's public library access settings. When true, some libraries may be excluded from results based on the teamspace's configuration (e.g., only verified libraries, selected libraries, or private repos only)." + } + }, + "required": [ + "results", + "searchFilterApplied" + ] + }, + "CodeSnippet": { + "type": "object", + "description": "A code snippet from library documentation", + "properties": { + "codeTitle": { + "type": "string", + "description": "Title of the code snippet" + }, + "codeDescription": { + "type": "string", + "description": "Description of what the code does" + }, + "codeLanguage": { + "type": "string", + "description": "Primary programming language" + }, + "codeTokens": { + "type": "integer", + "description": "Token count for the snippet" + }, + "codeId": { + "type": "string", + "description": "URL to source location" + }, + "pageTitle": { + "type": "string", + "description": "Title of the documentation page" + }, + "codeList": { + "type": "array", + "description": "Code examples in different languages", + "items": { + "$ref": "#/components/schemas/CodeExample" + } + }, + "isDynamic": { + "type": "boolean", + "description": "Whether this snippet was recovered from the dynamic source-code index instead of the primary docs index" + }, + "sourceFile": { + "type": "string", + "description": "Repo-relative source file path for dynamic snippets" + } + }, + "required": [ + "codeTitle", + "codeDescription", + "codeLanguage", + "codeTokens", + "codeId", + "pageTitle", + "codeList" + ] + }, + "CodeExample": { + "type": "object", + "description": "A single code example", + "properties": { + "language": { + "type": "string", + "description": "Programming language" + }, + "code": { + "type": "string", + "description": "The actual code content" + } + }, + "required": [ + "language", + "code" + ] + }, + "InfoSnippet": { + "type": "object", + "description": "A documentation snippet", + "properties": { + "pageId": { + "type": "string", + "description": "URL to source page" + }, + "breadcrumb": { + "type": "string", + "description": "Navigation breadcrumb path" + }, + "content": { + "type": "string", + "description": "The documentation content" + }, + "contentTokens": { + "type": "integer", + "description": "Token count for the content" + } + }, + "required": [ + "content", + "contentTokens" + ] + }, + "ContextResponse": { + "type": "object", + "description": "Documentation context response", + "properties": { + "codeSnippets": { + "type": "array", + "description": "Relevant code snippets", + "items": { + "$ref": "#/components/schemas/CodeSnippet" + } + }, + "infoSnippets": { + "type": "array", + "description": "Relevant documentation snippets", + "items": { + "$ref": "#/components/schemas/InfoSnippet" + } + }, + "rules": { + "type": "object", + "description": "Optional library-specific rules and guidelines", + "properties": { + "global": { + "type": "array", + "description": "Global team rules", + "items": { + "type": "string" + } + }, + "libraryOwn": { + "type": "array", + "description": "Rules defined by the library owner", + "items": { + "type": "string" + } + }, + "libraryTeam": { + "type": "array", + "description": "Library-specific rules from the team", + "items": { + "type": "string" + } + } + } + } + }, + "required": [ + "codeSnippets", + "infoSnippets" + ] + }, + "Error": { + "type": "object", + "description": "Standard error response", + "properties": { + "error": { + "type": "string", + "description": "Error code identifier" + }, + "message": { + "type": "string", + "description": "Human-readable error message" + } + }, + "required": [ + "error", + "message" + ] + }, + "ProjectStats": { + "type": "object", + "description": "Cumulative request counts for a library, broken down by request surface", + "properties": { + "page": { + "type": "integer", + "description": "Requests served to the context7.com web UI" + }, + "txt": { + "type": "integer", + "description": "Plain-text documentation requests" + }, + "mcp": { + "type": "integer", + "description": "Requests served via the Context7 MCP server" + }, + "cli": { + "type": "integer", + "description": "Requests served to the Context7 CLI" + } + }, + "required": [ + "page", + "txt", + "mcp", + "cli" + ] + }, + "DailyStatsPoint": { + "type": "object", + "description": "Per-day request counts for a library (counts *on* this date, not cumulative)", + "properties": { + "date": { + "type": "string", + "format": "date", + "description": "UTC date in `YYYY-MM-DD` format", + "example": "2025-01-15" + }, + "page": { + "type": "integer", + "description": "Requests served to the context7.com web UI on this date" + }, + "txt": { + "type": "integer", + "description": "Plain-text documentation requests on this date" + }, + "mcp": { + "type": "integer", + "description": "Requests served via the Context7 MCP server on this date" + }, + "cli": { + "type": "integer", + "description": "Requests served to the Context7 CLI on this date" + }, + "total": { + "type": "integer", + "description": "Sum of all request surfaces on this date (`page + txt + mcp + cli`)" + } + }, + "required": [ + "date", + "page", + "txt", + "mcp", + "cli", + "total" + ] + }, + "LibraryMetricsResponse": { + "type": "object", + "description": "Library usage metrics response", + "properties": { + "total": { + "$ref": "#/components/schemas/ProjectStats" + }, + "daily": { + "type": "array", + "description": "Per-day request counts (deltas, not cumulative), ordered from oldest to newest. Days with zero activity are omitted. Up to `days` points — fewer if the library has less history or had idle days in the window.", + "items": { + "$ref": "#/components/schemas/DailyStatsPoint" + } + }, + "mcpClients": { + "$ref": "#/components/schemas/McpClientMetrics" + }, + "topics": { + "type": "array", + "description": "Lifetime topic distribution, ordered by count descending", + "items": { + "$ref": "#/components/schemas/TopicCount" + } + }, + "countries": { + "type": "array", + "description": "Lifetime country distribution (ISO-2 codes), ordered by count descending", + "items": { + "$ref": "#/components/schemas/CountryCount" + } + } + }, + "required": [ + "total", + "daily", + "mcpClients", + "topics", + "countries" + ] + }, + "McpClientMetrics": { + "type": "object", + "description": "MCP client usage breakdown by day", + "properties": { + "dailyData": { + "type": "array", + "description": "Per-day MCP client unique-user breakdown, ordered from oldest to newest", + "items": { + "$ref": "#/components/schemas/McpDailyClientData" + } + } + }, + "required": [ + "dailyData" + ] + }, + "McpDailyClientData": { + "type": "object", + "description": "Per-day MCP client unique users for a library", + "properties": { + "date": { + "type": "string", + "format": "date", + "description": "UTC date in `YYYY-MM-DD` format", + "example": "2025-01-15" + }, + "uniqueUsersByClient": { + "type": "object", + "description": "Unique user count per MCP client identifier (e.g., `cursor`, `claude-code`, `codex`)", + "additionalProperties": { + "type": "integer" + } + }, + "totalUniqueUsers": { + "type": "integer", + "description": "Total unique users across all clients for this library on this date" + } + }, + "required": [ + "date", + "uniqueUsersByClient", + "totalUniqueUsers" + ] + }, + "TopicCount": { + "type": "object", + "description": "Topic with its lifetime request count", + "properties": { + "topic": { + "type": "string", + "description": "Normalized, lowercased topic string", + "example": "routing" + }, + "count": { + "type": "integer", + "description": "Number of requests that referenced this topic" + } + }, + "required": [ + "topic", + "count" + ] + }, + "CountryCount": { + "type": "object", + "description": "Country with its lifetime request count", + "properties": { + "country": { + "type": "string", + "description": "ISO 3166-1 alpha-2 country code", + "example": "US" + }, + "count": { + "type": "integer", + "description": "Number of requests originating from this country" + } + }, + "required": [ + "country", + "count" + ] + }, + "AddRepoRequest": { + "type": "object", + "description": "Request body for adding a Git repository", + "required": [ + "docsRepoUrl" + ], + "properties": { + "docsRepoUrl": { + "type": "string", + "format": "uri", + "description": "The repository URL" + }, + "gitToken": { + "type": "string", + "description": "Personal access token for private repositories. If not provided, the token from your OAuth connection at https://context7.com/add-library is used." + }, + "private": { + "type": "boolean", + "description": "Whether the repository is private" + }, + "skipVersionFiltering": { + "type": "boolean", + "description": "Skip filtering out version-specific documentation pages" + }, + "generateDocs": { + "type": "boolean", + "description": "Generate documentation from the repository source code. Applies to private repository submissions." + } + } + }, + "AddLibraryResponse": { + "type": "object", + "description": "Response after successfully submitting a library", + "properties": { + "libraryName": { + "type": "string", + "description": "The library identifier assigned — the URL path of the library on context7.com. `/owner/repo` for GitHub repositories, or `//` for other sources (e.g., `/vercel/next.js`, `/websites/uploadcare_com`). See [Library ID format](/api-guide#library-id-format)." + }, + "message": { + "type": "string", + "description": "Human-readable success message" + } + }, + "required": [ + "libraryName", + "message" + ] + }, + "SourceTypeStatus": { + "type": "object", + "description": "Whether a source type is enabled or disabled", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this source type is enabled" + } + }, + "required": [ + "enabled" + ] + }, + "PolicyResponse": { + "type": "object", + "description": "Complete teamspace policy configuration", + "properties": { + "sourceTypes": { + "type": "object", + "description": "Access settings for each documentation source type", + "properties": { + "public_repos": { + "$ref": "#/components/schemas/SourceTypeStatus" + }, + "private_sources": { + "$ref": "#/components/schemas/SourceTypeStatus" + }, + "confluence": { + "$ref": "#/components/schemas/SourceTypeStatus" + }, + "uploaded_files": { + "$ref": "#/components/schemas/SourceTypeStatus" + }, + "websites": { + "$ref": "#/components/schemas/SourceTypeStatus" + }, + "llmstxt": { + "$ref": "#/components/schemas/SourceTypeStatus" + } + }, + "required": [ + "public_repos", + "private_sources", + "confluence", + "uploaded_files", + "websites", + "llmstxt" + ] + }, + "libraryFilters": { + "type": "object", + "description": "Library access filters. Mode determines which sub-object is active.", + "properties": { + "mode": { + "type": "string", + "nullable": true, + "enum": [ + "quality", + "select", + null + ], + "description": "Filter mode: 'quality' for threshold-based filtering, 'select' for manual library selection" + }, + "quality": { + "type": "object", + "description": "Quality-mode settings (active when mode is 'quality')", + "properties": { + "requireVerified": { + "type": "boolean", + "description": "Restrict to verified libraries only" + }, + "minTrustScore": { + "type": "integer", + "nullable": true, + "description": "Minimum trust score, 0-10" + }, + "maxAgeDays": { + "type": "integer", + "nullable": true, + "description": "Maximum days since last update" + }, + "blockedLibraries": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Libraries excluded from results" + }, + "exceptedLibraries": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Libraries that bypass all quality filters, blocked list, and source type restrictions" + }, + "repoFilters": { + "type": "object", + "description": "Repo-specific quality filters", + "properties": { + "minStars": { + "type": "integer", + "nullable": true, + "description": "Minimum GitHub stars required" + }, + "allowedLicenses": { + "type": "array", + "items": { + "type": "string" + }, + "description": "SPDX license identifiers (e.g. 'MIT', 'Apache-2.0') that are allowed. Empty array means no license restriction. Applies to public repos only; non-repo source types pass through." + } + }, + "required": [ + "minStars", + "allowedLicenses" + ] + }, + "websiteFilters": { + "type": "object", + "description": "Website-specific quality filters", + "properties": { + "minBacklinks": { + "type": "integer", + "nullable": true, + "description": "Minimum number of backlinks required" + }, + "minReferringDomains": { + "type": "integer", + "nullable": true, + "description": "Minimum number of referring domains required" + }, + "minOrganicTraffic": { + "type": "integer", + "nullable": true, + "description": "Minimum monthly organic traffic required" + } + }, + "required": [ + "minBacklinks", + "minReferringDomains", + "minOrganicTraffic" + ] + } + }, + "required": [ + "requireVerified", + "minTrustScore", + "maxAgeDays", + "blockedLibraries", + "exceptedLibraries", + "repoFilters", + "websiteFilters" + ] + }, + "select": { + "type": "object", + "description": "Select-mode settings (active when mode is 'select')", + "properties": { + "allowedLibraries": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Libraries explicitly allowed" + } + }, + "required": [ + "allowedLibraries" + ] + } + }, + "required": [ + "mode", + "quality", + "select" + ] + }, + "accessibleLibraryCount": { + "type": "integer", + "description": "Number of public libraries currently accessible under these filters" + } + }, + "required": [ + "sourceTypes", + "libraryFilters", + "accessibleLibraryCount" + ] + }, + "ListOperation": { + "type": "object", + "description": "Incremental add/remove operation on a list of library identifiers or domains. Use 'clear' to remove all entries at once.", + "properties": { + "add": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Identifiers to add — library paths (e.g. '/org/repo', '/org') or domains (e.g. 'stripe.com')" + }, + "remove": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Identifiers to remove — library paths (e.g. '/org/repo', '/org') or domains (e.g. 'stripe.com')" + }, + "clear": { + "type": "boolean", + "description": "Set to true to remove all entries. Cannot be used together with 'add' or 'remove'." + } + } + }, + "LicenseListOperation": { + "type": "object", + "description": "Incremental add/remove operation on a list of SPDX license identifiers. Use 'clear' to remove all entries at once.", + "properties": { + "add": { + "type": "array", + "items": { + "type": "string", + "pattern": "^[A-Za-z0-9.+\\-_]+$", + "maxLength": 64 + }, + "description": "SPDX license identifiers to add (e.g. 'MIT', 'Apache-2.0', 'BSD-3-Clause')" + }, + "remove": { + "type": "array", + "items": { + "type": "string", + "pattern": "^[A-Za-z0-9.+\\-_]+$", + "maxLength": 64 + }, + "description": "SPDX license identifiers to remove" + }, + "clear": { + "type": "boolean", + "description": "Set to true to remove all entries. Cannot be used together with 'add' or 'remove'." + } + } + }, + "PatchPoliciesRequest": { + "type": "object", + "description": "Incremental policy update. All fields are optional — only provided fields are modified. At least one of 'sourceTypes' or 'libraryFilters' must be provided.", + "minProperties": 1, + "properties": { + "sourceTypes": { + "type": "object", + "description": "Enable or disable specific source types. Both can be provided in one request, but the same type cannot appear in both arrays.", + "properties": { + "enable": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "public_repos", + "private_sources", + "confluence", + "uploaded_files", + "websites", + "llmstxt" + ] + }, + "description": "Source types to enable" + }, + "disable": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "public_repos", + "private_sources", + "confluence", + "uploaded_files", + "websites", + "llmstxt" + ] + }, + "description": "Source types to disable" + } + } + }, + "libraryFilters": { + "type": "object", + "description": "Update library access filters.", + "properties": { + "mode": { + "type": "string", + "nullable": true, + "enum": [ + "quality", + "select", + null + ], + "description": "Filter mode (null to clear)" + }, + "quality": { + "type": "object", + "description": "Update quality-mode settings.", + "properties": { + "requireVerified": { + "type": "boolean", + "description": "Restrict to verified libraries only" + }, + "minTrustScore": { + "type": "integer", + "nullable": true, + "minimum": 0, + "maximum": 10, + "description": "Minimum trust score, 0-10 (null to clear)" + }, + "maxAgeDays": { + "type": "integer", + "nullable": true, + "minimum": 1, + "description": "Maximum age in days (null to clear)" + }, + "blockedLibraries": { + "$ref": "#/components/schemas/ListOperation" + }, + "exceptedLibraries": { + "$ref": "#/components/schemas/ListOperation" + }, + "repoFilters": { + "type": "object", + "description": "Update repo-specific quality filters.", + "properties": { + "minStars": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Minimum stars threshold (null to clear)" + }, + "allowedLicenses": { + "$ref": "#/components/schemas/LicenseListOperation" + } + } + }, + "websiteFilters": { + "type": "object", + "description": "Update website-specific quality filters.", + "properties": { + "minBacklinks": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Minimum backlinks threshold (null to clear)" + }, + "minReferringDomains": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Minimum referring domains threshold (null to clear)" + }, + "minOrganicTraffic": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Minimum organic traffic threshold (null to clear)" + } + } + } + } + }, + "select": { + "type": "object", + "description": "Update select-mode settings.", + "properties": { + "allowedLibraries": { + "$ref": "#/components/schemas/ListOperation" + } + } + } + } + } + } + }, + "RedirectErrorResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "type": "object", + "properties": { + "redirectUrl": { + "type": "string", + "description": "New location of the library" + } + } + } + ] + } + }, + "responses": { + "BadRequestError": { + "description": "Bad Request - Invalid input parameters", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "validationError": { + "summary": "Validation error", + "value": { + "error": "validation_error", + "message": "Library name is required" + } + }, + "invalidLibraryId": { + "summary": "Invalid library ID format", + "value": { + "error": "invalid_library_id", + "message": "Invalid library ID format. Expected: `/owner/repo` for GitHub repositories, or `//` for other sources (the URL path of the library on context7.com)" + } + } + } + } + } + }, + "ForbiddenError": { + "description": "Forbidden - Insufficient permissions or plan restrictions", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "accessDenied": { + "summary": "Library not in allowed list", + "value": { + "error": "access_denied", + "message": "Access denied: Library /owner/repo is not included in your allowed libraries" + } + }, + "insufficientRole": { + "summary": "Insufficient team role", + "value": { + "error": "forbidden", + "message": "Only team owners and admins can add private repositories" + } + }, + "planRequired": { + "summary": "Plan upgrade required", + "value": { + "error": "forbidden", + "message": "Private repositories require a pro plan or team. Upgrade at https://context7.com/plans" + } + } + } + } + } + }, + "NotFoundError": { + "description": "Not Found - Resource doesn't exist", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "libraryNotFound": { + "summary": "Library not found", + "value": { + "error": "library_not_found", + "message": "Library \"/owner/repo\" not found. Please check the library ID or your access permissions." + } + }, + "tagNotFound": { + "summary": "Version tag not found", + "value": { + "error": "tag_not_found", + "message": "Tag \"v1.0.0\" not found for library \"/owner/repo\". Available tags: v2.0.0, v1.5.0" + } + }, + "noSnippetsFound": { + "summary": "No snippets found", + "value": { + "error": "no_snippets_found", + "message": "Could not fetch documentation snippets from the library." + } + }, + "teamNotFound": { + "summary": "Team not found", + "value": { + "error": "team_not_found", + "message": "Team not found or access denied" + } + }, + "userNotFound": { + "summary": "User not found", + "value": { + "error": "user_not_found", + "message": "User not found" + } + }, + "noLibrariesFound": { + "summary": "No libraries matched search query", + "value": { + "error": "no_libraries_found", + "message": "No libraries found for \"nonexistent-lib\". Try a different search term." + } + } + } + } + } + }, + "InternalServerError": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "internal_error", + "message": "An error occurred while processing your request" + } + } + } + }, + "ServiceUnavailableError": { + "description": "Service Unavailable - Search service is temporarily unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "search_failed", + "message": "Search failed: Service temporarily unavailable" + } + } + } + }, + "AcceptedError": { + "description": "Accepted - Library not yet finalized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "library_not_finalized", + "message": "Library /owner/repo not finalized yet." + } + } + } + }, + "RedirectError": { + "description": "Moved Permanently - Library has been redirected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RedirectErrorResponse" + }, + "example": { + "error": "library_redirected", + "message": "Library /owner/repo has been redirected to this library: /new-owner/new-repo.", + "redirectUrl": "/new-owner/new-repo" + } + } + } + }, + "UnprocessableEntityError": { + "description": "Unprocessable Entity - Library is too large or has no code", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "tooLarge": { + "summary": "Library too large", + "value": { + "error": "library_too_large", + "message": "Library /owner/repo is too large to process." + } + }, + "noCode": { + "summary": "No code found", + "value": { + "error": "no_code_found", + "message": "Library /owner/repo has no or too few snippets found in documentation files." + } + } + } + } + } + }, + "UnauthorizedError": { + "description": "Unauthorized - Invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "invalid_api_key", + "message": "Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix." + } + } + } + }, + "AddLibrarySuccess": { + "description": "Library submitted successfully for processing", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddLibraryResponse" + }, + "example": { + "libraryName": "/owner/repo", + "message": "Repository submitted successfully" + } + } + } + }, + "DuplicateError": { + "description": "Conflict - Resource already exists", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "duplicate_repo", + "message": "This private repository is already in your team" + } + } + } + }, + "SpendingLimitError": { + "description": "Payment Required - the teamspace's configured monthly spending limit has been reached. A teamspace owner or admin can raise the limit in billing settings, or the cap will reset at the start of the next billing month.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "spending_limit_exceeded", + "message": "Monthly spending limit of $5.00 reached for this teamspace. An owner or admin can raise the limit at https://context7.com/dashboard/billing, or the cap will reset at the start of next month." + } + } + } + }, + "RateLimitError": { + "description": "Too Many Requests - Rate limit exceeded", + "headers": { + "Retry-After": { + "description": "Seconds until rate limit resets", + "schema": { + "type": "integer" + } + }, + "RateLimit-Limit": { + "description": "Request limit", + "schema": { + "type": "integer" + } + }, + "RateLimit-Remaining": { + "description": "Remaining requests", + "schema": { + "type": "integer" + } + }, + "RateLimit-Reset": { + "description": "Unix timestamp when limit resets", + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "rate_limit_exceeded", + "message": "Rate limit exceeded. Please try again later." + } + } + } + }, + "GatewayTimeoutError": { + "description": "Gateway Timeout - Processing timed out waiting for logs", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "timeout", + "message": "Request timed out. Please try again." + } + } + } + } + } + }, + "tags": [ + { + "name": "Search", + "description": "Search for libraries in the Context7 database" + }, + { + "name": "Context", + "description": "Retrieve documentation context for queries" + }, + { + "name": "Refresh", + "description": "Refresh existing libraries to fetch latest documentation" + }, + { + "name": "Policies", + "description": "Manage teamspace access policies and filters" + }, + { + "name": "Add Library", + "description": "Submit new libraries for documentation processing" + }, + { + "name": "Metrics", + "description": "Retrieve usage metrics for libraries" + } + ] +} diff --git a/docs/overview.mdx b/docs/overview.mdx new file mode 100644 index 0000000..970cfc1 --- /dev/null +++ b/docs/overview.mdx @@ -0,0 +1,51 @@ +--- +title: Intro +sidebarTitle: Intro +description: Context7 brings up-to-date, version-specific library documentation into your AI coding assistant +--- + +Context7 brings up-to-date, version-specific documentation and code examples directly into your AI coding assistant. That means no more outdated code or hallucinated APIs. + +## ❌ Without Context7 + +LLMs rely on outdated or generic information about the libraries you use: + +- ❌ Code examples based on old training data +- ❌ Hallucinated APIs that don't even exist +- ❌ Generic answers for old package versions + +## ✅ With Context7 + +Context7 MCP pulls up-to-date, version-specific documentation and code examples straight from the source — and places them directly into your prompt. + +Add `use context7` to your prompt in your AI coding assistant: + +```txt +Create a Next.js middleware that checks for a valid JWT in cookies and redirects unauthenticated users to `/login`. use context7 +``` + +```txt +Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7 +``` + +Context7 grounds your LLM with up-to-date documentation, ensuring that it always writes high quality code. + +- 1️⃣ Write your prompt naturally +- 2️⃣ Add `use context7` to your prompt +- 3️⃣ Get working code with current APIs + +No tab-switching, no hallucinated APIs that don't exist, no outdated code generation. + +## Next Steps + + + + Get set up in 2 minutes with your preferred AI coding assistant + + + Common issues and solutions + + + Unlock higher rate limits and use your private repositories + + diff --git a/docs/plans-pricing.mdx b/docs/plans-pricing.mdx new file mode 100644 index 0000000..513cf25 --- /dev/null +++ b/docs/plans-pricing.mdx @@ -0,0 +1,5 @@ +--- +title: Plans & Pricing +url: https://context7.com/plans +--- + diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico new file mode 100644 index 0000000..baa8d7b Binary files /dev/null and b/docs/public/favicon.ico differ diff --git a/docs/public/logo/logo-dark.svg b/docs/public/logo/logo-dark.svg new file mode 100644 index 0000000..6d3ab94 --- /dev/null +++ b/docs/public/logo/logo-dark.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/docs/public/logo/logo.png b/docs/public/logo/logo.png new file mode 100644 index 0000000..43ad820 Binary files /dev/null and b/docs/public/logo/logo.png differ diff --git a/docs/public/logo/logo.svg b/docs/public/logo/logo.svg new file mode 100644 index 0000000..75c17ba --- /dev/null +++ b/docs/public/logo/logo.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/docs/resources/all-clients.mdx b/docs/resources/all-clients.mdx new file mode 100644 index 0000000..9dac751 --- /dev/null +++ b/docs/resources/all-clients.mdx @@ -0,0 +1,1337 @@ +--- +title: MCP Clients +description: Installation examples for MCP clients +--- + +Context7 supports all MCP clients. Below are configuration examples for popular clients. If your client isn't listed, check its documentation for MCP server installation. To configure manually, use the Context7 server URL `https://mcp.context7.com/mcp` with your MCP client and pass your API key via the `CONTEXT7_API_KEY` header. + + + Looking for the easiest way to get started? Use `npx ctx7 setup` to configure Context7 + automatically, and `npx ctx7 remove` to remove the generated setup later. See the [CLI + docs](/clients/cli) for more details. + + + + For detailed guides including rules, skills, agents, and best practices, see + [Cursor](/clients/cursor) for rules and Composer integration tips, and [Claude + Code](/clients/claude-code) for skills, agents, commands, and plugin installation. + + +## OAuth Authentication + +Context7 MCP server supports OAuth 2.0 authentication for MCP clients that implement the [MCP OAuth specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). + +To use OAuth, change the endpoint from `/mcp` to `/mcp/oauth` in your client configuration: + +```diff +- "url": "https://mcp.context7.com/mcp" ++ "url": "https://mcp.context7.com/mcp/oauth" +``` + +OAuth is only available for remote HTTP connections. For local MCP connections using stdio transport, use API key authentication instead. + + + + + +Run this command. See [Claude Code MCP docs](https://code.claude.com/docs/en/mcp) for more info. + +#### Local Server Connection + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY +``` + +#### Remote Server Connection + +```sh +claude mcp add --scope user --header "CONTEXT7_API_KEY: YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp +``` + + + + + +Go to: `Cursor Settings` -> `Tools & MCP` -> `New MCP Server` + +Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://cursor.com/docs/context/mcp) for more info. + +Since Cursor 1.0, you can click the install button below for instant one-click installation. + +#### Remote Server Connection + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Local Server Connection + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +Add this to your Opencode configuration file. See [Opencode MCP docs](https://opencode.ai/docs/mcp-servers) for more info. + +#### Remote Server Connection + +```json +"mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "enabled": true + } +} +``` + +#### Local Server Connection + +```json +{ + "mcp": { + "context7": { + "type": "local", + "command": ["npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "enabled": true + } + } +} +``` + + + + + +See [OpenAI Codex MCP docs](https://developers.openai.com/codex/mcp) for more info. + +#### Context7 Plugin + +You can also install Context7 as a Codex plugin. It connects to the hosted MCP server and includes a documentation lookup skill. After installation, a browser window opens so you can log in via OAuth. + +```sh +codex plugin marketplace add upstash/context7 +codex plugin add context7@context7-marketplace +``` + +Start a new Codex thread after installation so Codex can load the plugin. + +#### Using CLI + +```sh +codex mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY +``` + +#### Local Server Connection + +Add this to your Codex configuration file (`~/.codex/config.toml` or `.codex/config.toml`). + +```toml +[mcp_servers.context7] +command = "npx" +args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] +startup_timeout_ms = 20_000 +``` + +#### Remote Server Connection + +```toml +[mcp_servers.context7] +url = "https://mcp.context7.com/mcp" +http_headers = { "CONTEXT7_API_KEY" = "YOUR_API_KEY" } +``` + +If you see startup timeout errors, try increasing `startup_timeout_ms` to `40_000`. + + + + + +Add this to your Antigravity MCP config file. See [Antigravity MCP docs](https://antigravity.google/docs/mcp) for more info. + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "serverUrl": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +The easiest way to install is the [Context7 VS Code extension](https://marketplace.visualstudio.com/items?itemName=Upstash.context7-mcp), which registers the server automatically and supports an API key via the `context7.apiKey` setting. See [VS Code](/clients/vscode) for details. For manual configuration, use the options below. + +[Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Install in VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) + +Add this to your VS Code MCP config file (`.vscode/mcp.json`). See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info. + +#### Remote Server Connection + +```json +{ + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Local Server Connection + +```json +{ + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +See [Kiro Model Context Protocol Documentation](https://kiro.dev/docs/mcp/configuration/) for details. + +[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=context7&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.context7.com%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D) + +1. Navigate `Kiro` > `MCP Servers` +2. Add a new MCP server by clicking the `+ Add` button. +3. Paste the configuration: + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +To use an API key in Kiro, add: + +```json +"headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" +} +``` + +See the [API keys guide](/howto/api-keys) for how to create one. + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +4. Click `Save` to apply. + + + + + +You can configure the Context7 MCP server in **Kilo Code** using either the UI or by editing your config file. See [Kilo Code MCP docs](https://kilo.ai/docs/automate/mcp/using-in-kilo-code) for more info. + +Kilo Code stores MCP servers in a `kilo.jsonc` file: + +- **Global** — `~/.config/kilo/kilo.jsonc` +- **Project** — `kilo.jsonc` in your project root or `.kilo/kilo.jsonc` (takes precedence) + +### Configure via Kilo Code UI + +1. Click the **Settings** icon in the sidebar toolbar. +2. Navigate to the **Agent Behaviour** tab. +3. Select the **MCP Servers** sub-tab. +4. Click **Add Server** and choose **Remote (HTTP)** or **Local (stdio)**. +5. Fill in the details and save. + +### Manual Configuration + +Add Context7 under the `mcp` key in your `kilo.jsonc`. + +#### Remote Server Connection + +```json +{ + "mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "enabled": true + } + } +} +``` + +#### Local Server Connection + +```json +{ + "mcp": { + "context7": { + "type": "local", + "command": ["npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "enabled": true + } + } +} +``` + + + + + +Add this to your Roo Code MCP configuration file. See [Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo) for more info. + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "type": "streamable-http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +Add this to your Devin Desktop MCP config file. See [Devin Desktop MCP docs](https://docs.devin.ai/desktop/cascade/mcp) for more info. + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "serverUrl": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +#### Remote Server Connection + +Open Claude Desktop and navigate to Settings > Connectors > Add Custom Connector. Enter the name as `Context7` and the remote MCP server URL as `https://mcp.context7.com/mcp`. + +#### Local Server Connection + +Open Claude Desktop developer settings and edit your `claude_desktop_config.json` file. See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +ChatGPT supports MCP servers through remote connectors via [Developer Mode](https://developers.openai.com/api/docs/guides/developer-mode) (beta). Available for Pro, Plus, Team, Enterprise, and Edu plans. + +#### 1. Enable Developer Mode + +Go to: `Settings` → `Apps` → `Advanced settings` → Enable `Developer Mode` + +#### 2. Create an App + +Go to: `Settings` → `Apps` → `Create App` + +Fill in the following: + +| Field | Value | +| ------------------ | ------------------------------------------------------------------------------------------- | +| **Name** | `Context7` | +| **Description** | `Fetch up-to-date documentation and code examples for any library directly from the source` | +| **MCP Server URL** | `https://mcp.context7.com/mcp/oauth` | + +> Accept the security notice and complete the one-time OAuth authorization. + +#### 3. Use in a Conversation + +Start a new chat → Click the plus icon → Hover over `More` → Select the `Context7` app. + +Alternatively, you can say `use context7` in your prompt and ChatGPT will automatically use the `Context7` app. + +See [OpenAI MCP docs](https://developers.openai.com/api/docs/mcp) for more info. + + + + + +The ChatGPT desktop app shares apps configured on the web. Set up the app on [chatgpt.com](https://chatgpt.com) first. + +#### 1. Enable Developer Mode (on the Web) + +Go to: `Settings` → `Apps` → `Advanced settings` → Enable `Developer Mode` + +#### 2. Create an App (on the Web) + +Go to: `Settings` → `Apps` → `Create App` + +Fill in the following: + +| Field | Value | +| ------------------ | ------------------------------------------------------------------------------------------- | +| **Name** | `Context7` | +| **Description** | `Fetch up-to-date documentation and code examples for any library directly from the source` | +| **MCP Server URL** | `https://mcp.context7.com/mcp/oauth` | + +> Accept the security notice and complete the one-time OAuth authorization. + +#### 3. Use in the Desktop App + +Open the ChatGPT desktop app → Start a new chat → ChatGPT will automatically use the `Context7` app when you ask it to. + +Apps configured on the web are automatically available in the desktop app. + +See [OpenAI MCP docs](https://developers.openai.com/api/docs/mcp) for more info. + + + + + +Use the Add manually feature and fill in the JSON configuration. See [Trae documentation](https://docs.trae.ai/ide/model-context-protocol?_lang=en) for more details. + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +You can easily install Context7 through the [Cline MCP Server Marketplace](https://cline.bot/mcp-marketplace) by following these instructions: + +1. Open **Cline**. +2. Click the hamburger menu icon to enter the **MCP Servers** section. +3. Use the search bar within the **Marketplace** tab to find _Context7_. +4. Click the **Install** button. + +Or you can directly edit MCP servers configuration: + +1. Open **Cline**. +2. Click the hamburger menu icon to enter the **MCP Servers** section. +3. Choose **Remote Servers** tab. +4. Click the **Edit Configuration** button. +5. Add context7 to `mcpServers`: + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` + + + + + +To configure Context7 MCP in Augment Code, you can use either the graphical interface or manual configuration. See [Augment Code MCP docs](https://docs.augmentcode.com/setup-augment/mcp) for more info. + +### Using the Augment Code UI + +1. Open the options menu in the upper right of the Augment panel. +2. Select **Settings**. +3. Navigate to the **MCP** section. +4. Click the **+** button to add a new server. +5. Enter the name **Context7** and the command: + + ``` + npx -y @upstash/context7-mcp@latest + ``` + +### Manual Configuration + +In the **MCP** section, use **Import from JSON** and paste the following (a top-level `mcpServers` object keyed by server name): + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +See [Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) for details. + +1. Open the Gemini CLI settings file at `~/.gemini/settings.json` +2. Add the following to the `mcpServers` object: + +```json +{ + "mcpServers": { + "context7": { + "httpUrl": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY", + "Accept": "application/json, text/event-stream" + } + } + } +} +``` + +Or, for a local server: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +Use the Hermes CLI or edit `~/.hermes/config.yaml` directly. See the [Hermes CLI docs](https://github.com/nousresearch/hermes-agent/blob/main/website/docs/reference/cli-commands.md) for more info. + +#### Remote Server Connection (API Key) + +Add this to your Hermes config file (`~/.hermes/config.yaml`). + +```yaml +mcp_servers: + context7: + url: "https://mcp.context7.com/mcp" + headers: + CONTEXT7_API_KEY: "YOUR_API_KEY" +``` + +#### Remote Server Connection (OAuth) + +```yaml +mcp_servers: + context7: + url: "https://mcp.context7.com/mcp/oauth" + auth: oauth +``` + +#### Using CLI (OAuth) + +```sh +hermes mcp add context7 --url https://mcp.context7.com/mcp/oauth --auth oauth +``` + +#### Local Server Connection + +```yaml +mcp_servers: + context7: + command: "npx" + args: ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] +``` + + +Start with the API key method if you want the most direct setup. Hermes also supports OAuth for remote MCP servers via `auth: oauth`. On headless setups, Hermes may print an authorization URL to stdout or logs for you to open manually. If `hermes mcp add ... --auth oauth` drops into the interactive agent without saving the server entry, add the `mcp_servers.context7` config manually, then run `hermes mcp test context7` to trigger the auth flow and verify the connection. + + + + + + +Use these alternatives to run the local Context7 MCP server with other runtimes. + +#### Bun + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +#### Deno + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": [ + "run", + "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", + "--allow-net", + "npm:@upstash/context7-mcp" + ] + } + } +} +``` + + + + + +Add the following configuration to `Repository` -> `Settings` -> `Code & automation` -> `Copilot` -> `MCP servers`. Only secrets named with the `COPILOT_MCP_` prefix are exposed to the MCP config, so store your key as a `COPILOT_MCP_CONTEXT7_API_KEY` Actions secret and reference it: + +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "$COPILOT_MCP_CONTEXT7_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` + +See the [official GitHub documentation](https://docs.github.com/en/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp) for more info. + + + + + +The easiest way is the Context7 plugin, which bundles the MCP server with a skill, an agent, and a command — see [GitHub Copilot CLI](/clients/copilot-cli). For manual configuration, open `~/.copilot/mcp-config.json` and add: + +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` + +Or, for a local server: + +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +Add this to your Amazon Q Developer CLI configuration file. See [Amazon Q Developer CLI docs](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html) for more details. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +See [Warp Model Context Protocol Documentation](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) for details. + +1. Navigate `Settings` > `Agents` > `MCP servers`. +2. Add a new MCP server by clicking the `+ Add` button. +3. Paste the configuration: + +```json +{ + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "env": {}, + "working_directory": null, + "start_on_launch": true + } +} +``` + +4. Click `Save`. + + + + + +Run this command in your terminal. See [Amp MCP docs](https://ampcode.com/manual#mcp) for more info. + +#### Without API Key (Basic Usage) + +```sh +amp mcp add context7 https://mcp.context7.com/mcp +``` + +#### With API Key (Higher Rate Limits & Private Repos) + +```sh +amp mcp add context7 --header "CONTEXT7_API_KEY=YOUR_API_KEY" https://mcp.context7.com/mcp +``` + + + + + +It can be installed via [Zed Extensions](https://zed.dev/extensions?query=Context7) or you can add this to your Zed `settings.json`. See [Zed MCP docs](https://zed.dev/docs/ai/mcp) for more info. + +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +To install Context7 MCP Server for any client automatically via [Smithery](https://smithery.ai/servers/@upstash/context7-mcp): + +```bash +npx -y @smithery/cli@latest install @upstash/context7-mcp --client +``` + +See the [Context7 server page on Smithery](https://smithery.ai/servers/@upstash/context7-mcp) for more details. + + + + + +See [JetBrains AI Assistant Documentation](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) for more details. + +1. In JetBrains IDEs, go to `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)` +2. Click `+ Add`. +3. Select the **HTTP** or **STDIO** tab and paste the JSON configuration. +4. Click `Apply` to save changes. + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +See [Qwen Code MCP Configuration](https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/) for details. + +### Using CLI Command + +By default, configurations are saved to the project scope (`.qwen/settings.json`). Use the `--scope user` flag to save to the user scope (`~/.qwen/settings.json`) instead. + +#### Remote Server Connection + +```sh +qwen mcp add --transport http context7 https://mcp.context7.com/mcp \ + --header "CONTEXT7_API_KEY: YOUR_API_KEY" \ + --header "Accept: application/json, text/event-stream" +``` + +#### Local Server Connection + +```sh +qwen mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY +``` + +### Manual Configuration + +1. Open the Qwen Code settings file at `~/.qwen/settings.json` (user scope) or `.qwen/settings.json` (project scope) +2. Add the following to the `mcpServers` object: + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "httpUrl": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY", + "Accept": "application/json, text/event-stream" + } + } + } +} +``` + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +1. Create a `Dockerfile`: + +```Dockerfile +FROM node:22-alpine +WORKDIR /app +RUN npm install -g @upstash/context7-mcp +CMD ["context7-mcp", "--transport", "stdio"] +``` + +2. Build the image: + +```bash +docker build -t context7-mcp . +``` + +3. Configure your MCP client: + +```json +{ + "mcpServers": { + "context7": { + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } +} +``` + + + + + +Context7 is available in the [Docker MCP Catalog](https://hub.docker.com/mcp/server/context7/overview) as a **remote** server, so you don't need to build, pull, or run a local image. The MCP Toolkit connects to the hosted endpoint for you. + +1. In Docker Desktop, open **MCP Toolkit → Catalog**, search for **Context7**, and enable it. +2. (Optional) In the server's **Config** tab, set your Context7 API key (`CONTEXT7_API_KEY`) for higher rate limits. The server also works without one. +3. Connect your MCP client to Docker's MCP gateway. Either run `docker mcp client connect ` (for example `vscode`, `cursor`, or `claude-desktop`), or add the gateway to your client config manually: + +```json +{ + "mcpServers": { + "MCP_DOCKER": { + "command": "docker", + "args": ["mcp", "gateway", "run"], + "type": "stdio" + } + } +} +``` + +The gateway exposes every server you've enabled in the MCP Toolkit, including Context7. Tools appear under the `MCP_DOCKER` server in your client. + + + + + +The configuration on Windows is slightly different. Use `cmd` to run npx: + +```json +{ + "mcpServers": { + "context7": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "disabled": false, + "autoApprove": [] + } + } +} +``` + + + + + +See [LM Studio MCP docs](https://lmstudio.ai/docs/app/plugins/mcp) for more information. + +#### One-click install: + +[![Add MCP Server context7 to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB1cHN0YXNoL2NvbnRleHQ3LW1jcCJdfQ%3D%3D) + +#### Manual set-up: + +1. Navigate to `Program` (right side) > `Install` > `Edit mcp.json`. +2. Paste the configuration: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +3. Click `Save`. + + + + + +See [Visual Studio MCP Servers documentation](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) for details. + +```json +{ + "inputs": [], + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +Or, for a local server: + +```json +{ + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +Add this to your Crush configuration file. See [Crush MCP docs](https://github.com/charmbracelet/crush#mcps) for more info. + +#### Remote Server Connection + +```json +{ + "$schema": "https://charm.land/crush.json", + "mcp": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Local Server Connection + +```json +{ + "$schema": "https://charm.land/crush.json", + "mcp": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +Open the "Settings" page, navigate to "Plugins," and enter: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +See [BoltAI's Documentation](https://docs.boltai.com/docs/plugins/mcp-servers) for more info. + + + + + +Edit your Rovo Dev CLI MCP config: + +```bash +acli rovodev mcp +``` + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + + + + + +1. Go to the Zencoder menu (...) +2. Select Agent tools +3. Click on Add custom MCP +4. Add the name and configuration: + +```json +{ + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] +} +``` + +5. Click Install. + + + + + +See [Qodo Gen docs](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps) for more details. + +1. Open Qodo Gen chat panel in VSCode or IntelliJ. +2. Click Connect more tools. +3. Click + Add new MCP. +4. Add the configuration: + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + + + + + +See [Local and Remote MCPs for Perplexity](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity) for more information. + +1. Navigate `Perplexity` > `Settings` +2. Select `Connectors`. +3. Click `Add Connector`. +4. Select `Advanced`. +5. Enter Server Name: `Context7` +6. Paste: + +```json +{ + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "command": "npx", + "env": {} +} +``` + +7. Click `Save`. + + + + + +Factory's droid supports MCP servers through its CLI. See [Factory MCP docs](https://docs.factory.ai/cli/configuration/mcp) for more info. + +#### Remote Server Connection + +```sh +droid mcp add context7 https://mcp.context7.com/mcp --type http --header "CONTEXT7_API_KEY: YOUR_API_KEY" +``` + +#### Local Server Connection + +```sh +droid mcp add context7 "npx -y @upstash/context7-mcp" --env CONTEXT7_API_KEY=YOUR_API_KEY +``` + + + + + +[Emdash](https://github.com/generalaction/emdash) is an orchestration layer for running multiple coding agents in parallel. + +Context7 is available as a built-in entry in Emdash's MCP catalog. Enable it from the MCP view and provide your `CONTEXT7_API_KEY` (optional, for higher rate limits). Emdash adapts and writes the MCP config into your selected coding agent's config (Codex, Claude Code, Cursor, etc.) for you. + +See the [Emdash repository](https://github.com/generalaction/emdash) for more information. + + + + + +Install the [context7.mcpb](https://github.com/upstash/context7/tree/master/packages/mcp/mcpb/context7.mcpb) file and add it to your client. See [MCP bundles docs](https://github.com/modelcontextprotocol/mcpb#mcp-bundles-mcpb) for more info. + + + + + +AnythingLLM supports MCP Servers through GUI. + +1. Navigate `AnythingLLM` > `Agents Skills` +2. Select `MCP Servers`. +3. Click `Edit MCP config`. +4. Paste. +5. Click to "Refresh" button. + +#### Remote Connection +```json +{ +"mcpServers": { + "context7": { + "type": "streamable", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } +} +} +``` + + + + diff --git a/docs/resources/developer.mdx b/docs/resources/developer.mdx new file mode 100644 index 0000000..030c784 --- /dev/null +++ b/docs/resources/developer.mdx @@ -0,0 +1,116 @@ +--- +title: Developer Guide +description: Set up and run Context7 MCP locally for development +--- + +This guide covers how to set up the Context7 MCP server locally for development and testing. + +## Getting Started + +Clone the project and install dependencies: + +```bash +git clone https://github.com/upstash/context7.git +cd context7 +pnpm i +``` + +Build: + +```bash +pnpm run build +``` + +Run the server: + +```bash +node packages/mcp/dist/index.js +``` + +## CLI Arguments + +`context7-mcp` accepts the following CLI flags: + +| Flag | Description | Default | +|------|-------------|---------| +| `--transport ` | Transport to use. Use `http` for remote HTTP server or `stdio` for local integration. | `stdio` | +| `--port ` | Port to listen on when using `http` transport. | `3000` | +| `--api-key ` | API key for authentication (or set `CONTEXT7_API_KEY` env var). | - | + + + Get your API key by creating an account at [context7.com/dashboard](https://context7.com/dashboard). + + +### Examples + +HTTP transport on port 8080: + +```bash +node packages/mcp/dist/index.js --transport http --port 8080 +``` + +Stdio transport with API key: + +```bash +node packages/mcp/dist/index.js --transport stdio --api-key YOUR_API_KEY +``` + +## Environment Variables + +You can use the `CONTEXT7_API_KEY` environment variable instead of passing the `--api-key` flag. This is useful for: + +- Storing API keys securely in `.env` files +- Integration with MCP server setups that use dotenv +- Tools that prefer environment variable configuration + + + The `--api-key` CLI flag takes precedence over the environment variable when both are provided. + + +### Using .env File + +```bash +# .env +CONTEXT7_API_KEY=your_api_key_here +``` + +### MCP Configuration with Environment Variable + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +## Local Development Configuration + +When developing locally, use this configuration to run from source: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7/packages/mcp/src/index.ts", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +## Testing with MCP Inspector + +Test your setup using the MCP Inspector: + +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp +``` + +This opens an interactive inspector to verify Context7 tools are working correctly. diff --git a/docs/resources/troubleshooting.mdx b/docs/resources/troubleshooting.mdx new file mode 100644 index 0000000..a82db88 --- /dev/null +++ b/docs/resources/troubleshooting.mdx @@ -0,0 +1,363 @@ +--- +title: Troubleshooting +description: Resolve common issues when setting up or using the Context7 MCP server +--- + +This guide helps you resolve common issues when setting up or using Context7 MCP. + +## Quick Checklist + +- Confirm Node.js v18+ is installed (`node --version`) +- Update to the latest Context7 MCP package (`@upstash/context7-mcp@latest`) +- Verify connectivity with `curl https://mcp.context7.com/ping` +- Add your API key to the configuration if you hit rate limits +- Enable debug logs (`DEBUG=*`) before collecting support information + + + **Skip Node.js issues entirely**: Use the remote server connection instead of local npx. Most MCP clients support connecting to `https://mcp.context7.com/mcp` directly, which requires no local Node.js installation. See [All MCP Clients](/resources/all-clients) for configuration examples. + + +## Common Fixes + +### Use Latest Version + +Add `@latest` to ensure you're using the most recent version: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +### Module Not Found / Use Alternative Runtimes + +If you encounter `ERR_MODULE_NOT_FOUND`, try `bunx` or `deno` instead of `npx`: + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": ["run", "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", "--allow-net", "npm:@upstash/context7-mcp"] + } + } +} +``` + +### ESM Resolution Issues + +For `Error: Cannot find module 'uriTemplate.js'`, use the `--experimental-vm-modules` flag: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` + +### TLS/Certificate Issues + +Use the `--experimental-fetch` flag: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"] + } + } +} +``` + +### Node.js Version + +Ensure you're using Node.js v18 or higher (`node --version`). + +## Platform-Specific Issues + +### Windows Issues + +#### Request Timeout Errors + +On Windows, some users may encounter request timeout errors with the default configuration. Try using the full path to Node.js and the installed package: + +```json +{ + "mcpServers": { + "context7": { + "command": "C:\\Program Files\\nodejs\\node.exe", + "args": [ + "C:\\Users\\yourname\\AppData\\Roaming\\npm\\node_modules\\@upstash\\context7-mcp\\dist\\index.js", + "--transport", + "stdio", + "--api-key", + "YOUR_API_KEY" + ] + } + } +} +``` + +Alternatively, use this configuration with `cmd`: + +```json +{ + "mcpServers": { + "context7": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +### macOS Issues + +#### Request Timeout Errors + +On macOS, some users may encounter the same request timeout errors. Use the full path to Node.js and the installed package: + +```json +{ + "mcpServers": { + "context7": { + "command": "/Users/yourname/.nvm/versions/node/v22.14.0/bin/node", + "args": [ + "/Users/yourname/.nvm/versions/node/v22.14.0/lib/node_modules/@upstash/context7-mcp/dist/index.js", + "--transport", + "stdio", + "--api-key", + "YOUR_API_KEY" + ] + } + } +} +``` + + + Replace `yourname` and the Node.js version (`v22.14.0`) with your actual username and installed + Node.js version. + + +## API and Connection Issues + +### Rate Limiting + +If you encounter rate limit errors: + +- **Get an API key**: Sign up at [context7.com/dashboard](https://context7.com/dashboard) for higher rate limits +- **Add the API key to your configuration**: + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +### Authentication Errors + +If you see `401 Unauthorized` errors: + +1. **Verify your API key** is correct and starts with `ctx7sk` +2. **Check the header format** - ensure the API key is properly set: + +For HTTP transport: + +```json +{ + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } +} +``` + +For stdio transport: + +```json +{ + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] +} +``` + +### Library Not Found + +If you get `404 Not Found` errors: + +1. **Verify the library ID** format is correct: `/owner/repo` or `/owner/repo/version` +2. **Search for the library** first using `resolve-library-id` tool +3. **Check if the library exists** at [context7.com](https://context7.com) + +## MCP Client-Specific Issues + +### Cursor + +- Make sure you're using Cursor 1.0 or later for the best MCP support +- Try both global (`~/.cursor/mcp.json`) and project-specific (`.cursor/mcp.json`) configurations +- Restart Cursor after changing the MCP configuration + +### VS Code + +- Ensure you have the latest version of VS Code with MCP support +- Check that the Copilot extension is installed and updated +- Restart VS Code after configuration changes + +### Claude Code + +- Verify the MCP server is added correctly with `claude mcp list` +- Check logs with `claude mcp logs context7` +- Try removing and re-adding the server + +## Configure HTTPS Proxy + +If you're behind a corporate proxy, configure Context7 to route through it. + +### Set Environment Variables + + + + ```bash + export https_proxy=http://proxy.example.com:8080 + export HTTPS_PROXY=http://proxy.example.com:8080 + ``` + + With authentication: + ```bash + export https_proxy=http://username:password@proxy.example.com:8080 + ``` + + + + + ```cmd + set https_proxy=http://proxy.example.com:8080 + set HTTPS_PROXY=http://proxy.example.com:8080 + ``` + + With authentication: + ```cmd + set https_proxy=http://username:password@proxy.example.com:8080 + ``` + + + + + ```powershell + $env:https_proxy = "http://proxy.example.com:8080" + $env:HTTPS_PROXY = "http://proxy.example.com:8080" + ``` + + + +### Or Configure in MCP Settings + +Add proxy directly to your MCP configuration: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "env": { + "https_proxy": "http://proxy.example.com:8080", + "HTTPS_PROXY": "http://proxy.example.com:8080" + } + } + } +} +``` + +Both lowercase and uppercase environment variables are supported. + + + After updating proxy settings, run `curl https://mcp.context7.com/ping` to confirm outbound + connectivity before restarting your IDE. + + +## Debugging Tips + +### Enable Verbose Logging + +Add debug output to your configuration: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "env": { + "DEBUG": "*" + } + } + } +} +``` + +### Test with MCP Inspector + +Test your setup independently: + +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp +``` + +This opens an interactive inspector to test Context7 tools. + +### Check Server Status + +Test that the remote server is reachable: + +```bash +curl https://mcp.context7.com/ping +``` + +Expected response: `{"status": "ok", "message": "pong"}` + +## Additional Support + +If these solutions don't resolve your issue: + +1. **Check GitHub Issues**: Search for similar problems at [github.com/upstash/context7/issues](https://github.com/upstash/context7/issues) +2. **Create a new issue**: Include your: + - Operating system and version + - Node.js version (`node --version`) + - MCP client and version + - Configuration (remove sensitive data like API keys) + - Error messages and logs +3. **Join Discord**: Get help from the community at [upstash.com/discord](https://upstash.com/discord) + +## Additional Resources + +- [Getting Started Guide](/overview) +- [Installation Instructions](https://github.com/upstash/context7#installation) +- [API Documentation](/api-guide) +- [Security & Privacy](/security/overview) diff --git a/docs/sdks/ts/commands/get-context.mdx b/docs/sdks/ts/commands/get-context.mdx new file mode 100644 index 0000000..2d63034 --- /dev/null +++ b/docs/sdks/ts/commands/get-context.mdx @@ -0,0 +1,154 @@ +--- +title: "Get Context" +description: "Retrieve documentation context for a library" +--- + +# Get Context + +Retrieve documentation context for a specific library. Returns documentation as a JSON array of documentation snippets (default) or as plain text. + +## Arguments + + + The user's question or task (used for relevance ranking) + + + + The library ID (e.g., `/facebook/react`) + + + + + + Format of the response + - `json`: Array of Documentation objects (default) + - `txt`: Plain text format + + Default: `"json"` + + + + +## Response + +The response type depends on the `type` option. + +### JSON Format (`type: "json"` or default) + +Returns `Documentation[]` - an array of documentation objects. + +### Text Format (`type: "txt"`) + +Returns a `string` containing the documentation context ready to use in LLM prompts. + + + + + Title of the documentation snippet + + + The documentation content (includes code blocks in markdown format) + + + Source identifier for the snippet + + + + +## Examples + + +```typescript JSON Format (Default) +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7(); + +const docs = await client.getContext( + "How do I use hooks?", + "/facebook/react" +); + +docs.forEach((doc) => { + console.log(doc.title); + console.log(doc.content); + console.log(doc.source); +}); +``` + +```typescript Text Format +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7(); + +const context = await client.getContext( + "How do I use hooks?", + "/facebook/react", + { type: "txt" } +); + +console.log(context); +``` + +```typescript Error Handling +import { Context7, Context7Error } from "@upstash/context7-sdk"; + +const client = new Context7(); + +try { + const context = await client.getContext( + "How to get started?", + "/invalid/library" + ); +} catch (error) { + if (error instanceof Context7Error) { + console.error("API Error:", error.message); + } else { + throw error; + } +} +``` + + +## Use Cases + +### Providing Context to LLMs + +```typescript +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7(); + +async function getDocsForPrompt(library: string, question: string) { + const context = await client.getContext(question, library); + + return ` +Here is the relevant documentation: + +${context} + +User question: ${question} +`; +} + +const prompt = await getDocsForPrompt("/facebook/react", "How do I use useEffect?"); +``` + +### Processing Individual Snippets + +```typescript +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7(); + +const docs = await client.getContext( + "How to create components?", + "/facebook/react", + { type: "json" } +); + +docs.forEach((doc) => { + console.log(`Title: ${doc.title}`); + console.log(`Source: ${doc.source}`); + console.log(`Content length: ${doc.content.length} chars`); +}); +``` diff --git a/docs/sdks/ts/commands/search-library.mdx b/docs/sdks/ts/commands/search-library.mdx new file mode 100644 index 0000000..46c72c8 --- /dev/null +++ b/docs/sdks/ts/commands/search-library.mdx @@ -0,0 +1,152 @@ +--- +title: "Search Library" +description: "Search available libraries" +--- + +# Search Library + +Search across available libraries. Returns an array of matching libraries with metadata useful for selection. + +## Arguments + + + The user's question or task (used for relevance ranking) + + + + The library name to search for + + +## Response + +Returns `Library[]` - an array of library objects. + + + + + Unique identifier for the library (e.g., `/facebook/react`) + + + Display name of the library + + + Brief description of the library + + + Total number of documentation snippets available + + + Trust score of the library + + + Benchmark score indicating documentation quality + + + Available versions + + + + +## Examples + + +```typescript Basic Search +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7(); + +const libraries = await client.searchLibrary( + "I need to build a UI", + "react" +); + +console.log(`Found ${libraries.length} libraries`); +libraries.forEach((library) => { + console.log(`${library.name}: ${library.description}`); +}); +``` + +```typescript Selecting Best Library +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7(); + +const libraries = await client.searchLibrary( + "I want to build a web app", + "next" +); + +const sorted = libraries.sort((a, b) => b.benchmarkScore - a.benchmarkScore); +const best = sorted[0]; + +console.log(`Best match: ${best.name} (score: ${best.benchmarkScore})`); +console.log(`Available snippets: ${best.totalSnippets}`); +``` + +```typescript Error Handling +import { Context7, Context7Error } from "@upstash/context7-sdk"; + +const client = new Context7(); + +try { + const libraries = await client.searchLibrary("query", "express"); + + if (libraries.length === 0) { + console.log("No libraries found"); + } else { + console.log(`Found ${libraries.length} libraries`); + } +} catch (error) { + if (error instanceof Context7Error) { + console.error("API Error:", error.message); + } else { + throw error; + } +} +``` + + +## Use Cases + +### Finding Libraries by Score + +```typescript +const libraries = await client.searchLibrary("state management", "redux"); + +const trusted = libraries.sort((a, b) => b.trustScore - a.trustScore); +console.log("Most trusted:", trusted[0].name); +``` + +### Checking Available Versions + +```typescript +const libraries = await client.searchLibrary("I want to use lodash", "lodash"); + +const library = libraries[0]; +if (library.versions) { + console.log(`Available versions: ${library.versions.join(", ")}`); +} +``` + +### Full Workflow + +```typescript +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7(); + +const libraries = await client.searchLibrary( + "I want to build a React app", + "react" +); + +const library = libraries[0]; +console.log(`Using: ${library.name} (${library.id})`); + +const context = await client.getContext( + "How do I create a component?", + library.id +); + +console.log(context); +``` diff --git a/docs/sdks/ts/getting-started.mdx b/docs/sdks/ts/getting-started.mdx new file mode 100644 index 0000000..f48fd26 --- /dev/null +++ b/docs/sdks/ts/getting-started.mdx @@ -0,0 +1,136 @@ +--- +title: "Getting Started" +description: "Get started with the Context7 TypeScript SDK" +--- + + + **Work in Progress**: This SDK is currently under active development. The API is subject to change and may introduce breaking changes in future releases. + + +# Getting Started + +`@upstash/context7-sdk` is a TypeScript SDK for Context7, enabling easier access to library documentation with full type coverage. + +Using `@upstash/context7-sdk` you can: + +- Search across available libraries +- Get documentation context for any library +- Access library metadata including trust scores and versions + +You can find the Github Repository [here](https://github.com/upstash/context7/tree/master/packages/sdk). + +## Install + + + ```shell npm + npm install @upstash/context7-sdk + ``` + +```shell pnpm +pnpm add @upstash/context7-sdk +``` + +```shell yarn +yarn add @upstash/context7-sdk +``` + +```shell bun +bun add @upstash/context7-sdk +``` + + + +## Usage + +### Initializing the Client + +To use the Context7 SDK, you need an API key. You can get your API key from the [Context7 Dashboard](https://context7.com/dashboard). + +#### Using environment variables + +The SDK automatically reads from environment variables if no API key is provided in the config: + +```bash +CONTEXT7_API_KEY="your_api_key_here" +``` + +When an environment variable is set, you can initialize the client without any parameters: + +```typescript +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7(); +``` + +#### Using a configuration object + +If you prefer to pass configuration in code, the constructor accepts a config object containing the apiKey value. This could be useful if your application needs to interact with multiple projects, each with a different configuration. + +```typescript +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7({ + apiKey: "YOUR_API_KEY", +}); +``` + + + The SDK checks for API keys in this order: 1. `config.apiKey` (if provided) 2. + `process.env.CONTEXT7_API_KEY` + + +## Quick Start Example + +```typescript +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7(); + +// Search for libraries +const libraries = await client.searchLibrary( + "I need to build a UI with components", + "react" +); +console.log(`Found ${libraries.length} libraries`); +console.log(libraries[0].id); // "/facebook/react" + +// Get documentation as JSON array (default) +const docs = await client.getContext( + "How do I use hooks?", + "/facebook/react" +); +console.log(docs[0].title, docs[0].content); + +// Get documentation context as plain text +const context = await client.getContext("How do I use hooks?", "/facebook/react", { + type: "txt", +}); +console.log(context); +``` + +## Error Handling + +The SDK throws `Context7Error` for API errors: + +```typescript +import { Context7, Context7Error } from "@upstash/context7-sdk"; + +const client = new Context7(); + +try { + const context = await client.getContext("query", "/invalid/library"); +} catch (error) { + if (error instanceof Context7Error) { + console.error("Context7 API Error:", error.message); + } else { + console.error("Unexpected error:", error); + } +} +``` + +## Next Steps + +Explore the SDK commands: + +- [Search Library](/sdks/ts/commands/search-library) - Search for libraries +- [Get Context](/sdks/ts/commands/get-context) - Retrieve library documentation context diff --git a/docs/security/auth-and-access-control.mdx b/docs/security/auth-and-access-control.mdx new file mode 100644 index 0000000..fbb82fc --- /dev/null +++ b/docs/security/auth-and-access-control.mdx @@ -0,0 +1,38 @@ +--- +title: Authentication and Access Control +--- + +This guide covers the authentication mechanisms and access controls available in Context7, including API key handling and enterprise identity features. + +## API Key Security + +- API keys use cryptographic random generation +- Keys are hashed and encrypted in our database +- Keys can be rotated at any time from your dashboard +- Rate limiting prevents abuse and unauthorized access + +## Enterprise SSO + +**Single Sign-On (SSO) is available for Enterprise plans.** + +### Supported SSO Providers + +- SAML 2.0 +- OAuth 2.0 +- OpenID Connect (OIDC) + +### Enterprise Features + +- Centralized user management +- Teamspace access controls +- Audit logs for compliance +- Custom authentication policies + +### Setup Guides + +For step-by-step configuration on self-hosted deployments, see: + +- [Microsoft Entra ID (SSO)](/enterprise/security/entra-sso) — wire up Entra ID sign-in for an On-Premise instance +- [Microsoft Entra ID](/enterprise/enterprise-managed-auth/entra) — proxy the Context7 MCP server through Azure APIM with Entra authentication + +Contact our sales team at [context7.com/contact](https://context7.com/contact) for Enterprise plan details. \ No newline at end of file diff --git a/docs/security/best-practices.mdx b/docs/security/best-practices.mdx new file mode 100644 index 0000000..6ae9555 --- /dev/null +++ b/docs/security/best-practices.mdx @@ -0,0 +1,31 @@ +--- +title: Best Practices for Users +sidebarTitle: Best Practices +description: Recommendations for using Context7 securely across credentials, repository access, and network usage +--- + +These recommendations cover how to use Context7 securely across credentials, repository access, and network usage. + +## Secure Your API Keys + +- Never commit API keys to version control +- Use environment variables for key storage +- Rotate keys regularly +- Use different keys for different environments +- Revoke unused or compromised keys immediately + +## Private Repositories + +For private repository access: + +- Only grant minimum required permissions +- Use dedicated API keys for private repos +- Regularly audit access permissions +- Consider using GitHub Apps with fine-grained permissions + +## Network Security + +- Use HTTPS for all API communications (enforced) +- Configure proxy settings securely if behind a firewall +- Monitor API usage for unusual patterns +- Implement request timeouts and retries diff --git a/docs/security/compliance-and-reporting.mdx b/docs/security/compliance-and-reporting.mdx new file mode 100644 index 0000000..a7d256b --- /dev/null +++ b/docs/security/compliance-and-reporting.mdx @@ -0,0 +1,35 @@ +--- +title: Compliance and Reporting +description: How Context7 handles security reporting, transparency, and compliance certifications +--- + +How Context7 handles security reporting, transparency, and compliance. + +## Reporting Security Issues + +If you discover a security vulnerability: + +1. **Do not** publicly disclose the issue +2. Report via [GitHub Security](https://github.com/upstash/context7/security) +3. Include detailed steps to reproduce the issue +4. Allow reasonable time for us to address the issue + +We take all security reports seriously and will respond promptly. + +## Open Source + +The Context7 MCP server is open source: + +- Code is publicly available on GitHub +- Community can audit and contribute +- Transparent implementation and practices + +Repository: [github.com/upstash/context7](https://github.com/upstash/context7) + +## Compliance Certifications + +Context7 benefits from Upstash's compliance certifications: + +- SOC 2 Type II +- GDPR compliant +- ISO 27001 (in progress) diff --git a/docs/security/data-privacy.mdx b/docs/security/data-privacy.mdx new file mode 100644 index 0000000..505baa0 --- /dev/null +++ b/docs/security/data-privacy.mdx @@ -0,0 +1,148 @@ +--- +title: Data Privacy +description: How Context7 handles query storage, retrieval scope, and your data +--- + +How Context7 handles privacy, retrieval scope, and data. + +## Query Privacy + +**Your original prompts and code stay with your AI assistant.** + +When you use Context7 through an MCP client, the AI assistant (not the user directly) formulates search queries to retrieve relevant documentation. Here is what happens: + +1. Your prompt is processed locally by your AI assistant (e.g., Cursor, Claude Code) +2. The AI assistant formulates a search query and library name based on your request +3. Only these formulated queries are sent to the Context7 API — your full prompt, source code, and conversation history are never transmitted +4. The MCP tool descriptions explicitly instruct the AI assistant to strip sensitive information (API keys, passwords, credentials, personal data, and proprietary code) from queries before sending + +### What is sent to the Context7 API + +- `query` — a search query formulated by the MCP client (not your original prompt) +- `libraryName` or `libraryId` — the library to look up +- API key (if provided, for authentication) +- MCP client name and version (e.g., IDE info, for analytics) +- Transport type (`stdio` or `http`) +- Client IP address, encrypted with AES-256-CBC (HTTP transport only, for rate limiting) + + + The MCP client formulates search queries on your behalf and is instructed not to include + sensitive or confidential information. Your full prompts, code, and conversation context + remain with your AI assistant and are never sent to Context7. + + +### Use of MCP Queries + +The search queries formulated by the MCP client (not your original prompts) are used server-side in two ways: + +**Documentation Reranking** + +MCP-formulated queries are passed to LLMs to rerank and select the most relevant documentation for your request. Context7 uses well-known, trusted LLM providers for this purpose — including **OpenAI**, **Google Gemini**, and **Anthropic**. + +**Benchmarking and Quality Improvement** + +MCP-formulated queries are anonymously stored and used to benchmark retrieval accuracy and improve the documentation matching pipeline over time. + +### Enterprise Controls + +- On-premise Enterprise plans can use their own LLM provider for code extraction and private library ranking +- On-premise Enterprise plans can disable public documentation usage, limiting context retrieval to privately indexed documentation only +- Enterprise plans can disable query storage for benchmarking — however, this may affect the quality of context retrieval over time + +Contact our sales team at [context7.com/contact](https://context7.com/contact) for Enterprise and on-premise plan details. + +## Customizing What Is Shared + +The Context7 MCP server is [open source](https://github.com/upstash/context7). If you want full control over what is sent as the `query` parameter, you can: + +1. Fork the [Context7 MCP repository](https://github.com/upstash/context7) +2. Edit the tool input descriptions in [`packages/mcp/src/index.ts`](https://github.com/upstash/context7/blob/master/packages/mcp/src/index.ts) — these descriptions instruct the AI assistant on how to formulate the query +3. Build and run your custom MCP server locally + + + The `query` parameter is used server-side for LLM-based reranking of documentation results. Modifying, redacting, or omitting the query can significantly reduce the relevance and quality of returned documentation. + + +## Customizing What Is Retrieved + +You can control retrieval scope from the **Policies** tab on your teamspace dashboard. + +### Source Type Access + +Toggle which types of documentation sources are accessible to your teamspace: + +- **Public Repositories** — open-source repositories from GitHub, GitLab, and Bitbucket +- **Websites** — documentation crawled from websites +- **llms.txt** — documentation from llms.txt files +- **Confluence** — Atlassian Confluence workspace pages and documentation +- **Uploaded Files** — uploaded OpenAPI specifications and PDFs +- **Private Sources** — private sources connected to this teamspace + + +![Source Type Access card showing toggles for each documentation source type](/images/dashboard/source-type-access.png) + + +### Library Filters + +Restrict which libraries are accessible to your teamspace. You can choose between two modes: + +- **Filter by Quality** — set criteria like verification status, minimum trust score, recency, blocked libraries, and more +- **Select Manually** — pick specific libraries or organizations + + +![Library Filters card showing quality filters and blocked libraries](/images/dashboard/public-repository-filters.png) + + +## Data Handling + +### Data Storage + +**Context7 does not store your source files.** + +- We only index and store **documentation** and **code examples** from repositories +- Your code, and source files are not stored or shared +- All indexed content is stored in a secure vector database optimized for retrieval + +**What we store:** + +- Library documentation +- Code examples from documentation +- Metadata about indexed libraries +- Queries formulated by the MCP client + +**What we don't store:** + +- Your source code +- Your original prompts or conversations +- Your conversations with AI assistants + + +### Privacy by Design + +- **Data Minimization**: We only collect and store what's necessary +- **Purpose Limitation**: Documentation data is used only for documentation retrieval +- **Storage Limitation**: Automated cleanup of outdated data +- **Transparency**: Clear documentation of what we collect and why + +### GDPR Compliance + +Context7 provides: + +- The right to access your data +- The right to delete your data +- Data portability options +- Clear consent mechanisms +- Privacy-first data processing + +### Data Residency + +All indexed documentation and metadata are stored within Upstash's SOC 2 compliant infrastructure in the United States and the European Union. +Cross-border data transfers comply with the EU General Data Protection Regulation (GDPR) and the EU-U.S. Data Privacy Framework (DPF), and enterprise customers can request region-specific data residency to meet local regulatory requirements. + + +### Data Retention + +- **Library Documentation**: Retained while the library is active and public +- **API Logs**: Retained for 30 days for debugging and analytics +- **User Data**: Retained according to your account status +- **Deleted Data**: Permanently removed within 30 days of deletion request diff --git a/docs/security/data-safety.mdx b/docs/security/data-safety.mdx new file mode 100644 index 0000000..a8f8491 --- /dev/null +++ b/docs/security/data-safety.mdx @@ -0,0 +1,19 @@ +--- +title: Data Safety +description: How Context7 detects prompt injection and malicious content in indexed documentation +--- + +## Prompt Injection and Malware Pattern Detection + +Context7 indexes documentation from public and private sources. To prevent malicious content from reaching AI assistants, Context7 employs a **layered malicious content detection system**. + + +![How our detection system works](/images/security/classifier_pipeline.png) + + +- **Robust Detection** — Content is analyzed using a classifier tailored for Context7 to identify prompt injection attempts and malware-related patterns +- **Targeted Validation** — Suspicious content is subjected to additional checks +- **Continuous Monitoring** — Flagged content is tracked and reviewed on an ongoing basis +- **Regular Updates** — Detection logic is updated to address evolving attack methods and new injection techniques + +This ensures that documentation retrieved through Context7 is safe to consume by both human developers and AI coding agents. diff --git a/docs/security/infrastructure.mdx b/docs/security/infrastructure.mdx new file mode 100644 index 0000000..6657a79 --- /dev/null +++ b/docs/security/infrastructure.mdx @@ -0,0 +1,56 @@ +--- +title: Infrastructure Security +sidebarTitle: Infrastructure +description: The platform-level protections behind Context7, including hosting, abuse prevention, and secure development +--- + +The operational and platform-level protections behind Context7, including hosted infrastructure, abuse prevention, and secure development practices. + +## Platform Infrastructure + +### SOC 2 Compliance + +Context7 runs on **SOC 2 compliant infrastructure** provided by Upstash. + +- Type II SOC 2 certified infrastructure +- Regular security audits and assessments +- Continuous monitoring and compliance checks +- Industry-standard security controls + +### Managed by Upstash + +Context7's infrastructure is managed by the experienced Upstash team: + +- 24/7 infrastructure monitoring +- Automated security patching +- DDoS protection and mitigation +- Redundant backups and disaster recovery +- Enterprise-grade reliability and uptime + +### Upstash Security Practices + +All security practices and certificates of Upstash apply to Context7 products: + +- **Data Encryption**: Encryption at rest and in transit (TLS 1.2+) +- **Network Security**: VPC isolation, firewall rules, and network segmentation +- **Access Control**: Role-based access control (RBAC) and least privilege principles +- **Audit Logging**: Comprehensive logging of all system activities +- **Incident Response**: Documented incident response procedures +- **Vulnerability Management**: Regular security scanning and penetration testing + + +## Rate Limiting and Abuse Prevention + +- IP-based rate limiting for anonymous requests +- API key-based rate limiting with tiered limits +- Automatic detection and blocking of abusive patterns +- Protection against DDoS and scraping attacks + +## Secure Development Practices + +- Regular security code reviews +- Automated dependency scanning +- Secure CI/CD pipelines +- Principle of least privilege for all systems +- Security testing in development lifecycle + diff --git a/docs/security/overview.mdx b/docs/security/overview.mdx new file mode 100644 index 0000000..c2cc56e --- /dev/null +++ b/docs/security/overview.mdx @@ -0,0 +1,59 @@ +--- +title: Security +sidebarTitle: Overview +description: An overview of Context7's security practices, data handling, and compliance measures +--- + +Context7 takes security and privacy seriously. This page outlines our security practices, data handling, and compliance measures. + +## Highlights + +- Your original prompts stay with your AI assistant; Context7 only receives search queries formulated by the MCP client, which is instructed to strip sensitive data before sending them +- Documentation is indexed inside SOC 2 compliant infrastructure operated by Upstash +- API keys are encrypted, rate limited, and easy to rotate from your dashboard +- Enterprise customers can enable SSO (SAML, OAuth, OIDC) and receive dedicated audit trails +- The [Context7 Addendum](https://upstash.com/trust/context7addendum.pdf), [Upstash Terms and Privacy Policy](https://upstash.com/docs/common/help/legal) applies to all users; see [trust.upstash.com](https://trust.upstash.com/) for full infrastructure compliance details, certifications + +## Security Areas + +Explore the main security topics in Context7: + + + + Learn how Context7 handles privacy, retrieval scope, and data. + + + Review platform protections, operational controls, abuse prevention, and secure development practices. + + + See how API keys, SSO, and enterprise access controls are handled. + + + Understand how Context7 detects malicious content and prevents it from reaching AI assistants. + + + Find reporting guidance, transparency commitments, and compliance details. + + + Follow practical recommendations for using Context7 securely. + + + +Context7 also uses verification badges to help signal trusted libraries. For full verification details, see [Library Verification](/howto/verification). +For more details on how Context7 handles quality and safety, see the [Quality and Safety in Context7](https://upstash.com/blog/context7-quality-and-safety) blog post. + +## Questions and Support + +For security-related questions: + +- Contact us through [GitHub Issues](https://github.com/upstash/context7/issues) +- Join our [Discord Community](https://upstash.com/discord) +- Enterprise customers: Contact your dedicated support team + +For privacy policy details, visit: [context7.com/privacy](https://context7.com/privacy) + +--- + +**Last Updated**: March 2026 + +We continuously improve our security practices. Check this page regularly for updates. diff --git a/docs/tips.mdx b/docs/tips.mdx new file mode 100644 index 0000000..ad881cf --- /dev/null +++ b/docs/tips.mdx @@ -0,0 +1,38 @@ +--- +title: Best Practices +description: Get the most out of Context7 with these best practices +--- + +## Add a Rule + +To avoid typing `use context7` in every prompt, add a rule to your MCP client to automatically invoke Context7 for code-related questions: + +- **Cursor**: `Cursor Settings > Rules` +- **Claude Code**: `CLAUDE.md` +- Or the equivalent in your MCP client + +**Example rule:** + +```txt +Always use Context7 MCP when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask. +``` + +## Use Library ID + +If you already know exactly which library you want to use, add its Context7 ID to your prompt. That way, Context7 MCP server can skip the library-matching step and directly continue with retrieving docs. + +```txt +Implement basic authentication with Supabase. use library /supabase/supabase for API and docs. +``` + +The slash syntax tells the MCP tool exactly which library to load docs for. + +## Specify a Version + +To get documentation for a specific library version, just mention the version in your prompt: + +```txt +How do I set up Next.js 14 middleware? use context7 +``` + +Context7 will automatically match the appropriate version. diff --git a/eslint.config.js b/eslint.config.js new file mode 100644 index 0000000..55fc57d --- /dev/null +++ b/eslint.config.js @@ -0,0 +1,37 @@ +import tseslint from "typescript-eslint"; +import eslintPluginPrettier from "eslint-plugin-prettier"; + +export default tseslint.config({ + // Base ESLint configuration + ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"], + languageOptions: { + ecmaVersion: 2020, + sourceType: "module", + parser: tseslint.parser, + parserOptions: {}, + globals: { + // Add Node.js globals + process: "readonly", + require: "readonly", + module: "writable", + console: "readonly", + }, + }, + // Settings for all files + linterOptions: { + reportUnusedDisableDirectives: true, + }, + // Apply ESLint recommended rules + extends: [tseslint.configs.recommended], + plugins: { + prettier: eslintPluginPrettier, + }, + rules: { + // TypeScript rules + "@typescript-eslint/explicit-module-boundary-types": "off", + "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }], + "@typescript-eslint/no-explicit-any": "warn", + // Prettier integration + "prettier/prettier": "error", + }, +}); diff --git a/gemini-extension.json b/gemini-extension.json new file mode 100644 index 0000000..fef69a4 --- /dev/null +++ b/gemini-extension.json @@ -0,0 +1,18 @@ +{ + "name": "context7", + "description": "Up-to-date code docs for any prompt", + "version": "1.0.0", + "settings": [ + { + "name": "API Key", + "description": "Context7 API key. Create new key at https://context7.com/dashboard.", + "envVar": "CONTEXT7_API_KEY" + } + ], + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "${CONTEXT7_API_KEY}"] + } + } +} diff --git a/i18n/README.ar.md b/i18n/README.ar.md new file mode 100644 index 0000000..100b1fb --- /dev/null +++ b/i18n/README.ar.md @@ -0,0 +1,318 @@ +# Context7 MCP - توثيق أكواد محدث لأي أمر برمجي + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) + +## ❌ بدون Context7 + +تعتمد النماذج اللغوية الكبيرة على معلومات قديمة أو عامة حول المكتبات التي تستخدمها. مما يؤدي إلى: + +- ❌ أمثلة أكواد قديمة مبنية على بيانات تدريب مضى عليها وقت طويل +- ❌ واجهات برمجة تطبيقات وهمية غير موجودة +- ❌ إجابات عامة لنسخ قديمة من الحزم + +## ✅ مع Context7 + +يستخرج Context7 MCP التوثيق والأمثلة البرمجية المحدثة مباشرة من المصدر — ويضعها في طلبك للنموذج. +أضف `use context7` إلى طلبك في Cursor: + +```txt +أنشئ مشروع Next.js بسيط باستخدام app router. use context7 +``` + +```txt +أنشئ سكربت لحذف الصفوف التي تكون فيها المدينة فارغة "" باستخدام بيانات اعتماد PostgreSQL. use context7 +``` + +يقوم Context7 بجلب الأمثلة المحدثة والتوثيق المناسب مباشرة إلى السياق. + +- 1️⃣ اكتب طلبك بشكل طبيعي +- 2️⃣ أخبر النموذج بـ `use context7` +- 3️⃣ احصل على أكواد تعمل مباشرة + لا حاجة للتنقل بين التبويبات، لا واجهات برمجة تطبيقات وهمية، لا أكواد قديمة. + +## 🛠️ البدء + +### المتطلبات + +- Node.js إصدار 18.0.0 أو أعلى +- Cursor، Devin Desktop، Claude Desktop أو أي عميل MCP آخر + +### التثبيت عبر Smithery + +لتثبيت Context7 MCP Server تلقائيًا لـ Claude Desktop: + +```bash +npx -y @smithery/cli install @upstash/context7-mcp --client claude +``` + +### التثبيت في Cursor + +اذهب إلى: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` +أو أضف هذا إلى ملف `~/.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### التثبيت باستخدام Bun + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### التثبيت باستخدام Deno + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": ["run", "--allow-env", "--allow-net", "npm:@upstash/context7-mcp"] + } + } +} +``` + +### التثبيت في Devin Desktop + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### التثبيت في VS Code + +```json +{ + "servers": { + "Context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### التثبيت في Zed + +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +### التثبيت في Claude Code + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest +``` + +### التثبيت في Claude Desktop + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### التثبيت في BoltAI + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### التثبيت في Copilot Coding Agent + +أضف التكوين التالي إلى قسم `mcp` في ملف إعدادات Copilot Coding Agent الخاص بك Repository->Settings->Copilot->Coding agent->MCP configuration: + +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` + +لمزيد من المعلومات، راجع [التوثيق الرسمي على GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). + +### باستخدام Docker + +**Dockerfile:** + +```Dockerfile +FROM node:18-alpine +WORKDIR /app +RUN npm install -g @upstash/context7-mcp@latest +CMD ["context7-mcp"] +``` + +**بناء الصورة:** + +```bash +docker build -t context7-mcp . +``` + +**التهيئة داخل العميل:** + +```json +{ + "mcpServers": { + "Context7": { + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } +} +``` + +### التثبيت في Windows + +```json +{ + "mcpServers": { + "github.com/upstash/context7-mcp": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"], + "disabled": false, + "autoApprove": [] + } + } +} +``` + +### الأدوات المتوفرة + +- `resolve-library-id`: يحول اسم مكتبة عام إلى معرف متوافق مع Context7. + - `query` (مطلوب): سؤال أو مهمة المستخدم (لترتيب الصلة) + - `libraryName` (مطلوب): اسم المكتبة للبحث عنها +- `query-docs`: يستخرج التوثيق حسب المعرف. + - `libraryId` (مطلوب): معرف Context7 المتوافق الدقيق (مثل `/mongodb/docs`, `/vercel/next.js`) + - `query` (مطلوب): السؤال أو المهمة للحصول على توثيق ذي صلة + +## التطوير + +```bash +pnpm i +pnpm run build +``` + +**التهيئة المحلية:** + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` + +**الاختبار باستخدام MCP Inspector:** + +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp@latest +``` + +## استكشاف الأخطاء + +### ERR_MODULE_NOT_FOUND + +استخدم `bunx` بدلاً من `npx`. + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### مشاكل في ESM + +جرّب إضافة: + +```json +{ + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] +} +``` + +### أخطاء عميل MCP + +1. أزل `@latest` +2. جرّب `bunx` +3. جرّب `deno` +4. تأكد أنك تستخدم Node v18 أو أحدث + +## إخلاء مسؤولية + +المشاريع المدرجة في Context7 مساهم بها من المجتمع، ولا يمكن ضمان دقتها أو أمانها بشكل كامل. الرجاء الإبلاغ عن أي محتوى مريب باستخدام زر "الإبلاغ". + +## Context7 في الإعلام + +- [Better Stack: "أداة مجانية تجعل Cursor أذكى 10x"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "أفضل MCP Server لمساعدين الذكاء الاصطناعي البرمجيين"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Context7 + SequentialThinking: هل هذا AGI؟](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [تحديث جديد من Context7 MCP](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [إعداد Context7 في VS Code](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Context7: MCP جديد سيغير البرمجة](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [Cline & RooCode + Context7: قوة مضاعفة](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [أفضل 5 MCP Servers لتجربة برمجة ساحرة](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## سجل النجوم + +[![Star History Chart](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## الترخيص + +MIT diff --git a/i18n/README.de.md b/i18n/README.de.md new file mode 100644 index 0000000..bb800b1 --- /dev/null +++ b/i18n/README.de.md @@ -0,0 +1,330 @@ +# Context7 MCP - Aktuelle Dokumentation für jeden Prompt + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [In VS Code installieren (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) + +## ❌ Ohne Context7 + +KI-Sprachmodelle (LLMs) greifen auf veraltete oder allgemeine Informationen über die von dir verwendeten Bibliotheken zurück. Das Ergebnis: + +- ❌ Codebeispiele sind veraltet und basieren auf Trainingsdaten, die Jahre alt sind +- ❌ Halluzinierte APIs, die gar nicht existieren +- ❌ Generische Antworten für alte Paketversionen + +## ✅ Mit Context7 + +Context7 MCP holt aktuelle, versionsspezifische Dokumentationen und Codebeispiele direkt aus der Quelle und fügt sie in deinen Prompt ein. +Füge `use context7` zu deinem Prompt in Cursor hinzu: + +```txt +Erstelle ein einfaches Next.js-Projekt mit dem App Router. use context7 +``` + +```txt +Erstelle ein Skript zum Löschen der Zeilen, in denen die Stadt "" ist, mit PostgreSQL-Anmeldedaten. use context7 +``` + +Context7 holt aktuelle Codebeispiele und Dokumentationen direkt in den Kontext deines LLMs. + +- 1️⃣ Schreibe deinen Prompt auf natürliche Weise +- 2️⃣ Weise das LLM an, context7 zu verwenden, mit `use context7` +- 3️⃣ Erhalte funktionierende Codeantworten + Kein Tab-Switching, keine halluzinierten APIs, die nicht existieren, keine veralteten Code-Generierungen. + +## 🛠️ Erste Schritte + +### Anforderungen + +- Node.js >= v18.0.0 +- Cursor, Devin Desktop, Claude Desktop oder ein anderer MCP-Client + +### Installation über Smithery + +Um den Context7 MCP Server für Claude Desktop automatisch über [Smithery](https://smithery.ai/server/@upstash/context7-mcp) zu installieren: + +```bash +npx -y @smithery/cli install @upstash/context7-mcp --client claude +``` + +### Installation in Cursor + +Gehe zu: `Einstellungen` -> `Cursor-Einstellungen` -> `MCP` -> `Neuen globalen MCP-Server hinzufügen` +Der empfohlene Ansatz ist die folgende Konfiguration in deine Cursor-Datei `~/.cursor/mcp.json` einzufügen. Siehe die [Cursor MCP Dokumentation](https://docs.cursor.com/context/model-context-protocol) für mehr Informationen. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +
+Alternative: Bun verwenden + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +
+ +
+Alternative: Deno verwenden + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": ["run", "--allow-net", "npm:@upstash/context7-mcp"] + } + } +} +``` +
+ +### Installation in Devin Desktop +Füge dies zu deiner Devin Desktop MCP-Konfigurationsdatei hinzu. Siehe die [Devin Desktop MCP Dokumentation](https://docs.devin.ai/desktop/cascade/mcp) für mehr Informationen. +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Installation in VS Code +[In VS Code installieren (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[In VS Code Insiders installieren (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +Füge dies zu deiner VS Code MCP-Konfigurationsdatei hinzu. Siehe die [VS Code MCP Dokumentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) für mehr Informationen. +```json +{ + "servers": { + "Context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Installation in Zed +Es kann über [Zed Extensions](https://zed.dev/extensions?query=Context7) installiert werden oder du kannst dies zu deiner Zed `settings.json` hinzufügen. Siehe die [Zed Context Server Dokumentation](https://zed.dev/docs/assistant/context-servers) für mehr Informationen. +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +### Installation in Claude Code +Führe diesen Befehl aus. Siehe die [Claude Code MCP Dokumentation](https://docs.anthropic.com/de/docs/claude-code/mcp) für mehr Informationen. +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest +``` + +### Installation in Claude Desktop +Füge dies zu deiner Claude Desktop `claude_desktop_config.json` Datei hinzu. Siehe die [Claude Desktop MCP Dokumentation](https://modelcontextprotocol.io/quickstart/user) für mehr Informationen. +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Installation im Copilot Coding Agent +Füge die folgende Konfiguration zum Abschnitt `mcp` deiner Copilot Coding Agent-Konfigurationsdatei hinzu (Repository->Settings->Copilot->Coding agent->MCP configuration): +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Weitere Informationen findest du in der [offiziellen GitHub-Dokumentation](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). + +### Installation im Copilot CLI +1. Öffne die MCP-Konfigurationsdatei von Copilot CLI. Der Ort ist `~/.copilot/mcp-config.json` (wobei `~` dein Home-Verzeichnis ist). +2. Füge Folgendes zum `mcpServers`-Objekt in deiner `mcp-config.json`-Datei hinzu: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Oder für einen lokalen Server: +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +Falls die `mcp-config.json`-Datei nicht existiert, erstelle sie. + +### Docker verwenden +Wenn du den MCP-Server lieber in einem Docker-Container ausführen möchtest: +1. **Docker-Image erstellen:** + Erstelle zunächst ein `Dockerfile` im Projekt-Root (oder an einem Ort deiner Wahl): +
+ Klicke, um den Dockerfile-Inhalt zu sehen + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # Installiere die neueste Version global + RUN npm install -g @upstash/context7-mcp@latest + # Port freigeben, falls nötig (optional, abhängig von der MCP-Client-Interaktion) + # EXPOSE 3000 + # Standardbefehl zum Ausführen des Servers + CMD ["context7-mcp"] + ``` +
+ + Baue dann das Image mit einem Tag (z.B. `context7-mcp`). **Stelle sicher, dass Docker Desktop (oder der Docker-Daemon) läuft.** Führe den folgenden Befehl in dem Verzeichnis aus, in dem du das `Dockerfile` gespeichert hast: + ```bash + docker build -t context7-mcp . + ``` +2. **Konfiguriere deinen MCP-Client:** + Aktualisiere die Konfiguration deines MCP-Clients, um den Docker-Befehl zu verwenden. + _Beispiel für eine cline_mcp_settings.json:_ + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _Hinweis: Dies ist eine Beispielkonfiguration. Bitte beziehe dich auf die spezifischen Beispiele für deinen MCP-Client (wie Cursor, VS Code usw.), die weiter oben in dieser README beschrieben sind, um die Struktur anzupassen (z.B. `mcpServers` vs `servers`). Stelle außerdem sicher, dass der Bildname in `args` mit dem beim `docker build`-Befehl verwendeten Tag übereinstimmt._ + +### Verfügbare Tools +- `resolve-library-id`: Löst einen allgemeinen Bibliotheksnamen in eine Context7-kompatible Bibliotheks-ID auf. + - `query` (erforderlich): Die Frage oder Aufgabe des Benutzers (zur Relevanzranking) + - `libraryName` (erforderlich): Der Name der zu suchenden Bibliothek +- `query-docs`: Ruft die Dokumentation für eine Bibliothek mit einer Context7-kompatiblen Bibliotheks-ID ab. + - `libraryId` (erforderlich): Exakte Context7-kompatible Bibliotheks-ID (z.B. `/mongodb/docs`, `/vercel/next.js`) + - `query` (erforderlich): Die Frage oder Aufgabe, für die relevante Dokumentation abgerufen werden soll + +## Entwicklung +Klone das Projekt und installiere die Abhängigkeiten: +```bash +pnpm i +``` +Bauen: +```bash +pnpm run build +``` + +### Lokales Konfigurationsbeispiel +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/pfad/zum/ordner/context7-mcp/src/index.ts"] + } + } +} +``` + +### Testen mit MCP Inspector +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp@latest +``` + +## Fehlerbehebung + +### ERR_MODULE_NOT_FOUND +Wenn du diesen Fehler siehst, versuche `bunx` anstelle von `npx` zu verwenden. +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +Dies löst häufig Probleme bei der Modulauflösung, besonders in Umgebungen, in denen `npx` Pakete nicht ordnungsgemäß installiert oder auflöst. + +### ESM-Auflösungsprobleme +Wenn du einen Fehler wie `Error: Cannot find module 'uriTemplate.js'` bekommst, versuche mit dem Flag `--experimental-vm-modules` auszuführen: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` + +### MCP-Client-Fehler +1. Versuche, `@latest` aus dem Paketnamen zu entfernen. +2. Versuche, `bunx` als Alternative zu verwenden. +3. Versuche, `deno` als Alternative zu verwenden. +4. Stelle sicher, dass du Node v18 oder höher verwendest, um native Fetch-Unterstützung mit `npx` zu haben. + +## Haftungsausschluss +Context7-Projekte werden von der Community beigetragen, und obwohl wir uns bemühen, eine hohe Qualität aufrechtzuerhalten, können wir die Genauigkeit, Vollständigkeit oder Sicherheit aller Bibliotheksdokumentationen nicht garantieren. Die in Context7 aufgeführten Projekte werden von ihren jeweiligen Eigentümern entwickelt und gepflegt, nicht von Context7. Wenn du auf verdächtige, unangemessene oder potenziell schädliche Inhalte stößt, verwende bitte die Schaltfläche "Melden" auf der Projektseite, um uns sofort zu benachrichtigen. Wir nehmen alle Berichte ernst und werden gemeldete Inhalte umgehend überprüfen, um die Integrität und Sicherheit unserer Plattform zu gewährleisten. Durch die Nutzung von Context7 erkennst du an, dass du dies nach eigenem Ermessen und auf eigenes Risiko tust. + +## Context7 in den Medien +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income stream surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income stream surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) + +## Verlauf der Sterne +[![Stern-Historien-Diagramm](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## Lizenz +MIT diff --git a/i18n/README.es.md b/i18n/README.es.md new file mode 100644 index 0000000..5a71509 --- /dev/null +++ b/i18n/README.es.md @@ -0,0 +1,257 @@ +# Context7 MCP - Documentación Actualizada Para Cualquier Prompt + +[![Sitio Web](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![insignia smithery](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [Instalar en VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522context7%2522%252C%2522config%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540upstash%252Fcontext7-mcp%2540latest%2522%255D%257D%257D) + +## ❌ Sin Context7 + +Los LLMs dependen de información desactualizada o genérica sobre las bibliotecas que utilizas. Obtienes: + +- ❌ Ejemplos de código desactualizados y basados en datos de entrenamiento de hace un año +- ❌ APIs inventadas que ni siquiera existen +- ❌ Respuestas genéricas para versiones antiguas de paquetes + +## ✅ Con Context7 + +El Context7 MCP obtiene documentación y ejemplos de código actualizados y específicos de la versión directamente desde la fuente, y los coloca directamente en tu prompt. +Añade `use context7` a tu prompt en Cursor: + +```txt +Crea un proyecto básico de Next.js con app router. use context7 +``` + +```txt +Crea un script para eliminar las filas donde la ciudad es "" dadas las credenciales de PostgreSQL. use context7 +``` + +Context7 obtiene ejemplos de código y documentación actualizados directamente en el contexto de tu LLM. + +- 1️⃣ Escribe tu prompt de forma natural +- 2️⃣ Dile al LLM que `use context7` +- 3️⃣ Obtén respuestas de código que funcionan + Sin cambiar de pestaña, sin APIs inventadas que no existen, sin generaciones de código desactualizadas. + +## 🛠️ Empezando + +### Requisitos + +- Node.js >= v18.0.0 +- Cursor, Devin Desktop, Claude Desktop u otro Cliente MCP + +### Instalando vía Smithery + +Para instalar Context7 MCP Server para Claude Desktop automáticamente vía [Smithery](https://smithery.ai/server/@upstash/context7-mcp): + +```bash +npx -y @smithery/cli install @upstash/context7-mcp --client claude +``` + +### Instalar en Cursor + +Ve a: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` +Pegar la siguiente configuración en tu archivo `~/.cursor/mcp.json` de Cursor es el metodo recomendado. Consulta la [documentación de MCP de Cursor](https://docs.cursor.com/context/model-context-protocol) para más información. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +
+Alternativa: Usar Bun + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +
+ +
+Alternativa: Usar Deno + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": ["run", "--allow-net", "npm:@upstash/context7-mcp"] + } + } +} +``` +
+ +### Instalar en Devin Desktop +Añade esto a tu archivo de configuración MCP de Devin Desktop. Consulta la [documentación de MCP de Devin Desktop](https://docs.devin.ai/desktop/cascade/mcp) para más información. +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Instalar en VS Code +[Instalar en VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522context7%2522%252C%2522config%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540upstash%252Fcontext7-mcp%2540latest%2522%255D%257D%257D) +[Instalar en VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522context7%2522%252C%2522config%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540upstash%252Fcontext7-mcp%2540latest%2522%255D%257D%257D) +Añade esto a tu archivo de configuración MCP de VS Code. Consulta la [documentación de VS Code MCP](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) para más información. +```json +{ + "servers": { + "Context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Instalar en Claude Code +Ejecuta este comando. Consulta la [documentación de MCP de Claude Code](https://docs.anthropic.com/es/docs/claude-code/mcp) para más información. +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest +``` + +### Instalar en Claude Desktop +Añade esto a tu archivo `claude_desktop_config.json` de Claude Desktop. Consulta la [documentación de MCP de Claude Desktop](https://modelcontextprotocol.io/quickstart/user) para más información. +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Instalar en Copilot Coding Agent +Agrega la siguiente configuración a la sección `mcp` de tu archivo de configuración de Copilot Coding Agent (Repository->Settings->Copilot->Coding agent->MCP configuration): +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Para más información, consulta la [documentación oficial de GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). + +### Instalar en Copilot CLI +1. Abre el archivo de configuración MCP de Copilot CLI. La ubicación es `~/.copilot/mcp-config.json` (donde `~` es tu directorio home). +2. Agrega lo siguiente al objeto `mcpServers` en tu archivo `mcp-config.json`: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +O, para un servidor local: +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +Si el archivo `mcp-config.json` no existe, créalo. + +### Herramientas Disponibles +- `resolve-library-id`: Resuelve un nombre de una biblioteca general en un ID de biblioteca compatible con Context7. + - `query` (requerido): La pregunta o tarea del usuario (para ranking de relevancia) + - `libraryName` (requerido): El nombre de la biblioteca a buscar +- `query-docs`: Obtiene documentación para una biblioteca utilizando un ID de biblioteca compatible con Context7. + - `libraryId` (requerido): ID exacto compatible con Context7 (por ejemplo, `/mongodb/docs`, `/vercel/next.js`) + - `query` (requerido): La pregunta o tarea para obtener documentación relevante + +## Desarrollo +Clona el proyecto e instala las dependencias: +```bash +pnpm i +``` +Compila: +```bash +pnpm run build +``` + +### Ejemplo de Configuración Local +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/ruta/a/la/carpeta/context7-mcp/src/index.ts"] + } + } +} +``` + +### Probando con MCP Inspector +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp@latest +``` + +## Solución de Problemas + +### ERR_MODULE_NOT_FOUND +Si ves este error, intenta usar `bunx` en lugar de `npx`. +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +Esto a menudo resuelve problemas de resolución de módulos, especialmente en entornos donde `npx` no instala o resuelve paquetes correctamente. + +### Errores del Cliente MCP +1. Intenta eliminar `@latest` del nombre del paquete. +2. Intenta usar `bunx` como alternativa. +3. Intenta usar `deno` como alternativa. + +## Context7 en los Medios +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income stream surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income stream surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) + +## Historial de Estrellas +[![Gráfico de Historial de Estrellas](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## Licencia +MIT diff --git a/i18n/README.fr.md b/i18n/README.fr.md new file mode 100644 index 0000000..009bb5b --- /dev/null +++ b/i18n/README.fr.md @@ -0,0 +1,359 @@ +# Context7 MCP - Documentation à jour pour vos prompts + +[![Site Web](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![badge smithery](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [Installer dans VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) + +## ❌ Sans Context7 + +Les LLMs s’appuient sur des informations obsolètes ou génériques concernant les bibliothèques que vous utilisez. Vous obtenez : + +- ❌ Des exemples de code obsolètes, basés sur des données d’entraînement vieilles d’un an +- ❌ Des APIs inventées qui n’existent même pas +- ❌ Des réponses génériques pour d’anciennes versions de packages + +## ✅ Avec Context7 + +Context7 MCP récupère la documentation et les exemples de code à jour, spécifiques à la version, directement à la source — et les place dans votre prompt. +Ajoutez `use context7` à votre prompt dans Cursor : + +```txt +Crée un projet Next.js basique avec app router. use context7 +``` + +```txt +Crée un script pour supprimer les lignes où la ville est "" avec des identifiants PostgreSQL. use context7 +``` + +Context7 apporte des exemples de code et de la documentation à jour directement dans le contexte de votre LLM. + +- 1️⃣ Rédigez votre prompt naturellement +- 2️⃣ Dites au LLM `use context7` +- 3️⃣ Obtenez des réponses de code qui fonctionnent + Plus besoin de changer d’onglet, plus d’APIs inventées, plus de code obsolète. + +## 🛠️ Démarrage + +### Prérequis + +- Node.js >= v18.0.0 +- Cursor, Devin Desktop, Claude Desktop ou un autre client MCP + +### Installation via Smithery + +Pour installer Context7 MCP Server pour Claude Desktop automatiquement via [Smithery](https://smithery.ai/server/@upstash/context7-mcp) : + +```bash +npx -y @smithery/cli install @upstash/context7-mcp --client claude +``` + +### Installation dans Cursor + +Allez dans : `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` +La méthode recommandée est de coller la configuration suivante dans votre fichier `~/.cursor/mcp.json`. Voir la [documentation Cursor MCP](https://docs.cursor.com/context/model-context-protocol) pour plus d’informations. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +
+Alternative : Utiliser Bun + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +
+ +
+Alternative : Utiliser Deno + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": ["run", "--allow-net", "npm:@upstash/context7-mcp"] + } + } +} +``` +
+ +### Installation dans Devin Desktop +Ajoutez ceci à votre fichier de configuration MCP Devin Desktop. Voir la [documentation Devin Desktop MCP](https://docs.devin.ai/desktop/cascade/mcp) pour plus d’informations. +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Installation dans VS Code +[Installer dans VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Installer dans VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +Ajoutez ceci à votre fichier de configuration MCP VS Code. Voir la [documentation VS Code MCP](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) pour plus d'informations. +```json +{ + "servers": { + "Context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Installation dans Zed +Peut être installé via [Zed Extensions](https://zed.dev/extensions?query=Context7) ou en ajoutant ceci à votre `settings.json` Zed. Voir la [documentation Zed Context Server](https://zed.dev/docs/assistant/context-servers). +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +### Installation dans Claude Code +Exécutez cette commande. Voir la [documentation Claude Code MCP](https://docs.anthropic.com/fr/docs/claude-code/mcp). +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest +``` + +### Installation dans Claude Desktop +Ajoutez ceci à votre fichier `claude_desktop_config.json`. Voir la [documentation Claude Desktop MCP](https://modelcontextprotocol.io/quickstart/user). +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Installation dans BoltAI +Ouvrez la page "Settings" de l'application, naviguez jusqu'à "Plugins", et entrez le JSON suivant : +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +Une fois enregistré, saisissez dans le chat `query-docs` suivi de votre ID de documentation Context7 (par exemple, `query-docs /nuxt/ui`). Plus d'informations sont disponibles sur le [site de documentation BoltAI](https://docs.boltai.com/docs/plugins/mcp-servers). Pour BoltAI sur iOS, [consultez ce guide](https://docs.boltai.com/docs/boltai-mobile/mcp-servers). + +### Installation dans Copilot Coding Agent +Ajoutez la configuration suivante à la section `mcp` de votre fichier de configuration Copilot Coding Agent (Repository->Settings->Copilot->Coding agent->MCP configuration) : +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Pour plus d'informations, consultez la [documentation officielle GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). + +### Installation dans Copilot CLI +1. Ouvrez le fichier de configuration MCP de Copilot CLI. L'emplacement est `~/.copilot/mcp-config.json` (où `~` est votre répertoire personnel). +2. Ajoutez ce qui suit à l'objet `mcpServers` dans votre fichier `mcp-config.json` : +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Ou, pour un serveur local : +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +Si le fichier `mcp-config.json` n'existe pas, créez-le. + +### Utilisation avec Docker +Si vous préférez exécuter le serveur MCP dans un conteneur Docker : +1. **Construisez l’image Docker :** + Créez un `Dockerfile` à la racine du projet (ou ailleurs) : +
+ Voir le contenu du Dockerfile + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # Installer la dernière version en global + RUN npm install -g @upstash/context7-mcp@latest + # Exposer le port par défaut si besoin (optionnel) + # EXPOSE 3000 + # Commande par défaut + CMD ["context7-mcp"] + ``` +
+ + Puis, construisez l’image : + ```bash + docker build -t context7-mcp . + ``` +2. **Configurez votre client MCP :** + Mettez à jour la configuration de votre client MCP pour utiliser la commande Docker. + _Exemple pour un fichier cline_mcp_settings.json :_ + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _Note : Ceci est un exemple. Adaptez la structure selon votre client MCP (voir plus haut dans ce README). Assurez-vous que le nom de l’image dans `args` correspond au tag utilisé lors du build._ + +### Installation sous Windows +La configuration sous Windows est légèrement différente par rapport à Linux ou macOS (_`Cline` est utilisé dans l'exemple_). Le même principe s'applique à d'autres éditeurs; référez-vous à la configuration de `command` et `args`. +```json +{ + "mcpServers": { + "github.com/upstash/context7-mcp": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"], + "disabled": false, + "autoApprove": [] + } + } +} +``` + +### Outils disponibles +- `resolve-library-id` : Résout un nom de bibliothèque général en un ID compatible Context7. + - `libraryName` (obligatoire) +- `query-docs` : Récupère la documentation d’une bibliothèque via un ID Context7. + - `libraryId` (obligatoire) + +## Développement +Clonez le projet et installez les dépendances : +```bash +pnpm i +``` +Build : +```bash +pnpm run build +``` + +### Exemple de configuration locale +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` + +### Tester avec MCP Inspector +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp@latest +``` + +## Dépannage + +### ERR_MODULE_NOT_FOUND +Si vous voyez cette erreur, essayez d’utiliser `bunx` à la place de `npx`. +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +Cela résout souvent les problèmes de résolution de modules, surtout si `npx` n’installe ou ne résout pas correctement les packages. + +### Problèmes de résolution ESM +Si vous rencontrez une erreur comme : `Error: Cannot find module 'uriTemplate.js'` essayez d'exécuter avec le drapeau `--experimental-vm-modules` : +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` + +### Erreurs client MCP +1. Essayez de retirer `@latest` du nom du package. +2. Essayez d'utiliser `bunx` comme alternative. +3. Essayez d'utiliser `deno` comme alternative. +4. Assurez-vous d'utiliser Node v18 ou supérieur pour avoir le support natif de fetch avec `npx`. + +## Clause de non-responsabilité +Les projets Context7 sont des contributions de la communauté, et bien que nous nous efforcions de maintenir une haute qualité, nous ne pouvons garantir l'exactitude, l'exhaustivité ou la sécurité de toute la documentation des bibliothèques. Les projets listés dans Context7 sont développés et maintenus par leurs propriétaires respectifs, et non par Context7. Si vous rencontrez un contenu suspect, inapproprié ou potentiellement nuisible, veuillez utiliser le bouton "Signaler" sur la page du projet pour nous le faire savoir immédiatement. Nous prenons tous les signalements au sérieux et examinerons rapidement les contenus signalés pour maintenir l'intégrité et la sécurité de notre plateforme. En utilisant Context7, vous reconnaissez que vous le faites à votre propre discrétion et à vos risques et périls. + +## Context7 dans les médias +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income stream surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income stream surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## Historique des stars +[![Graphique d'historique des stars](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## Licence +MIT diff --git a/i18n/README.id-ID.md b/i18n/README.id-ID.md new file mode 100644 index 0000000..f25819a --- /dev/null +++ b/i18n/README.id-ID.md @@ -0,0 +1,918 @@ +# Context7 MCP - Dokumentasi Kode Terkini Untuk Setiap Permintaan + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[![English](https://img.shields.io/badge/docs-English-blue)](../README.md) [![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./README.zh-TW.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](./README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentação em Português (Brasil)]()](./README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./README.ru.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./README.uk.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./README.ar.md) + +## ❌ Tanpa Context7 + +LLM bergantung pada informasi yang sudah usang atau generik tentang pustaka yang Anda gunakan. Anda mendapatkan: + +- ❌ Contoh kode yang sudah usang dan berdasarkan data pelatihan dari tahun lalu +- ❌ API yang diimajinasikan tidak pernah ada +- ❌ Jawaban generik untuk versi paket yang lama + +## ✅ Dengan Context7 + +Context7 MCP mengambil dokumentasi dan contoh kode terkini yang spesifik versi langsung dari sumbernya — dan menempatkannya langsung ke dalam prompt Anda. +Tambahkan `use context7` ke prompt Anda di Cursor: + +```txt +Buat middleware Next.js yang memeriksa JWT valid di cookie dan mengarahkan pengguna yang tidak terautentikasi ke `/login`. use context7 +``` + +```txt +Konfigurasikan skrip Cloudflare Worker untuk menyimpan respons API JSON selama lima menit. use context7 +``` + +Context7 mengambil contoh kode dan dokumentasi terkini langsung ke konteks LLM. + +- 1️⃣ Tulis permintaan Anda secara alami +- 2️⃣ Beri tahu LLM untuk `use context7` +- 3️⃣ Dapatkan jawaban kode yang berfungsi + Tidak perlu berpindah tab, tidak ada API yang diimajinasikan yang tidak ada, tidak ada hasil kode usang. + +## 📚 Menambahkan Proyek + +Kunjungi [panduan penambahan proyek](https://context7.com/docs/adding-libraries) untuk mempelajari cara menambahkan (atau memperbarui) pustaka favorit Anda ke Context7. + +## 🛠️ Instalasi + +### Persyaratan + +- Node.js >= v18.0.0 +- Cursor, Devin Desktop, Claude Desktop, atau klien MCP lainnya +
+Menginstal melalui Smithery + +Untuk menginstal Context7 MCP Server untuk klien apa pun secara otomatis melalui [Smithery](https://smithery.ai/server/@upstash/context7-mcp): + +```bash +npx -y @smithery/cli@latest install @upstash/context7-mcp --client --key +``` + +Anda dapat menemukan kunci Smithery Anda di [halaman web Smithery.ai](https://smithery.ai/server/@upstash/context7-mcp). + +
+ +
+Instal di Cursor + +Pergi ke: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` +Menyalin konfigurasi berikut ke file `~/.cursor/mcp.json` Anda adalah pendekatan yang direkomendasikan. Anda juga dapat menginstalnya di proyek tertentu dengan membuat `.cursor/mcp.json` di folder proyek Anda. Lihat [dokumentasi Cursor MCP](https://docs.cursor.com/context/model-context-protocol) untuk info lebih lanjut. +> Sejak Cursor 1.0, Anda dapat mengklik tombol instal di bawah untuk instalasi satu klik instan. + +#### Koneksi Server Remote Cursor +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Koneksi Server Lokal Cursor +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+Alternatif: Gunakan Bun + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoiYnVueCAteSBAdXBzdGFzaC9jb250ZXh0Ny1tY3AifQ%3D%3D) +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Alternatif: Gunakan Deno + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoiZGVubyBydW4gLS1hbGxvdy1lbnYgLS1hbGxvdy1uZXQgbnBtOkB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": ["run", "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", "--allow-net", "npm:@upstash/context7-mcp"] + } + } +} +``` +
+ +
+ +
+Instal di Devin Desktop + +Tambahkan ini ke file konfigurasi MCP Devin Desktop Anda. Lihat [dokumentasi MCP Devin Desktop](https://docs.devin.ai/desktop/cascade/mcp) untuk info lebih lanjut. + +#### Koneksi Server Remote Devin Desktop + +```json +{ + "mcpServers": { + "context7": { + "serverUrl": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Koneksi Server Lokal Devin Desktop + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instal di Trae + +Gunakan fitur Tambah secara manual dan isi informasi konfigurasi JSON untuk server MCP tersebut. +Untuk detail lebih lanjut, kunjungi [dokumentasi Trae](https://docs.trae.ai/ide/model-context-protocol?_lang=en). + +#### Koneksi Server Remote Trae + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Koneksi Server Lokal Trae + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instal di VS Code + +[Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Install in VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +Tambahkan ini ke file konfigurasi MCP VS Code Anda. Lihat [dokumentasi MCP VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) untuk info lebih lanjut. + +#### Koneksi Server Remote VS Code + +```json +"mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Koneksi Server Lokal VS Code + +```json +"mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instal di Visual Studio 2022 + +Anda dapat mengonfigurasi Context7 MCP di Visual Studio 2022 dengan mengikuti [dokumentasi Server MCP Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022). +Tambahkan ini ke file konfigurasi MCP Visual Studio Anda (lihat [dokumentasi Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) untuk detailnya): +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } + } +} +``` +Atau, untuk server lokal: +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } + } +} +``` +Untuk informasi dan pemecahan masalah lebih lanjut, lihat [dokumentasi Server MCP Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022). +
+ +
+Instal di Zed + +Dapat diinstal melalui [Ekstensi Zed](https://zed.dev/extensions?query=Context7) atau Anda dapat menambahkan ini ke `settings.json` Zed Anda. Lihat [dokumentasi Server Konteks Zed](https://zed.dev/docs/assistant/context-servers) untuk info lebih lanjut. +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +
+ +
+Instal di Gemini CLI + +Lihat [Konfigurasi Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md) untuk detailnya. +1. Buka file pengaturan Gemini CLI. Lokasinya adalah `~/.gemini/settings.json` (di mana `~` adalah direktori home Anda). +2. Tambahkan berikut ini ke objek `mcpServers` di file `settings.json` Anda: +```json +{ + "mcpServers": { + "context7": { + "httpUrl": "https://mcp.context7.com/mcp" + } + } +} +``` +Atau, untuk server lokal: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Jika objek `mcpServers` tidak ada, buatlah. +
+ +
+Instal di Claude Code + +Jalankan perintah ini. Lihat [dokumentasi MCP Claude Code](https://docs.anthropic.com/id/docs/claude-code/mcp) untuk info lebih lanjut. + +#### Koneksi Server Lokal Claude Code + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp +``` + +#### Koneksi Server Remote Claude Code + +```sh +claude mcp add --scope user --transport http context7 https://mcp.context7.com/mcp +``` +
+ +
+Instal di Claude Desktop + +Tambahkan ini ke file `claude_desktop_config.json` Claude Desktop Anda. Lihat [dokumentasi MCP Claude Desktop](https://modelcontextprotocol.io/quickstart/user) untuk info lebih lanjut. +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+ +Instal di Cline + + +Anda dapat dengan mudah menginstal Context7 melalui [Pasar Server MCP Cline](https://cline.bot/mcp-marketplace) dengan mengikuti petunjuk berikut: +1. Buka **Cline**. +2. Klik ikon menu hamburger (☰) untuk masuk ke bagian **Server MCP**. +3. Gunakan bilah pencarian di tab **Marketplace** untuk menemukan *Context7*. +4. Klik tombol **Instal**. +
+ +
+Instal di BoltAI + +Buka halaman "Pengaturan" aplikasi, navigasikan ke "Plugin," dan masukkan JSON berikut: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Setelah disimpan, masukkan di obrolan `query-docs` diikuti oleh ID dokumentasi Context7 Anda (contoh: `query-docs /nuxt/ui`). Informasi lebih lanjut tersedia di [situs dokumentasi BoltAI](https://docs.boltai.com/docs/plugins/mcp-servers). Untuk BoltAI di iOS, [lihat panduan ini](https://docs.boltai.com/docs/boltai-mobile/mcp-servers). +
+ +
+Menggunakan Docker + +Jika Anda lebih suka menjalankan server MCP dalam wadah Docker: +1. **Bangun Gambar Docker:** + Pertama, buat `Dockerfile` di direktori utama proyek (atau di mana pun Anda inginkan): +
+ Klik untuk melihat isi Dockerfile + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # Instal versi terbaru secara global + RUN npm install -g @upstash/context7-mcp + # Ekspor port default jika diperlukan (opsional, tergantung pada interaksi klien MCP) + # EXPOSE 3000 + # Perintah default untuk menjalankan server + CMD ["context7-mcp"] + ``` +
+ + Kemudian, bangun gambar menggunakan tag (contoh: `context7-mcp`). **Pastikan Docker Desktop (atau daemon Docker) berjalan.** Jalankan perintah berikut di direktori yang sama tempat Anda menyimpan `Dockerfile`: + ```bash + docker build -t context7-mcp . + ``` +2. **Konfigurasikan Klien MCP Anda:** + Perbarui konfigurasi klien MCP Anda untuk menggunakan perintah Docker. + _Contoh untuk cline_mcp_settings.json:_ + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _Catatan: Ini adalah contoh konfigurasi. Silakan merujuk ke contoh spesifik untuk klien MCP Anda (seperti Cursor, VS Code, dll.) sebelumnya di README ini untuk menyesuaikan struktur (misalnya, `mcpServers` vs `servers`). Juga, pastikan nama gambar di `args` sesuai dengan tag yang digunakan saat perintah `docker build`._ +
+ +
+Instal di Windows + +Konfigurasi di Windows sedikit berbeda dibandingkan Linux atau macOS (_`Cline` digunakan sebagai contoh_). Prinsip yang sama berlaku untuk editor lainnya; lihat konfigurasi `command` dan `args`. +```json +{ + "mcpServers": { + "github.com/upstash/context7-mcp": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"], + "disabled": false, + "autoApprove": [] + } + } +} +``` +
+ +
+Instal di Augment Code + +Untuk mengonfigurasi Context7 MCP di Augment Code, Anda dapat menggunakan antarmuka grafis atau konfigurasi manual. + +### **A. Menggunakan UI Augment Code** +1. Klik menu hamburger. +2. Pilih **Pengaturan**. +3. Navigasikan ke bagian **Alat**. +4. Klik tombol **+ Tambah MCP**. +5. Masukkan perintah berikut: + ``` + npx -y @upstash/context7-mcp@latest + ``` +6. Beri nama MCP: **Context7**. +7. Klik tombol **Tambah**. + Setelah server MCP ditambahkan, Anda dapat mulai menggunakan fitur dokumentasi kode terkini Context7 langsung di Augment Code. +--- + +### **B. Konfigurasi Manual** +1. Tekan Cmd/Ctrl Shift P atau pergi ke menu hamburger di panel Augment +2. Pilih Edit Pengaturan +3. Di bawah Lanjutan, klik Edit di settings.json +4. Tambahkan konfigurasi server ke array `mcpServers` di objek `augment.advanced` +```json +"augment.advanced": { + "mcpServers": [ + { + "name": "context7", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + ] +} +``` +Setelah server MCP ditambahkan, restart editor Anda. Jika Anda menerima kesalahan, periksa sintaks untuk memastikan tanda kurung atau koma penutup tidak hilang. +
+ +
+Instal di Roo Code + +Tambahkan ini ke file konfigurasi MCP Roo Code Anda. Lihat [dokumentasi MCP Roo Code](https://docs.roocode.com/features/mcp/using-mcp-in-roo) untuk info lebih lanjut. + +#### Koneksi Server Remote Roo Code + +```json +{ + "mcpServers": { + "context7": { + "type": "streamable-http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Koneksi Server Lokal Roo Code + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instal di Zencoder + +Untuk mengonfigurasi Context7 MCP di Zencoder, ikuti langkah-langkah berikut: +1. Pergi ke menu Zencoder (...) +2. Dari menu dropdown, pilih Alat Agen +3. Klik Tambah MCP Kustom +4. Tambahkan nama dan konfigurasi server dari bawah, dan pastikan untuk menekan tombol Instal +```json +{ + "command": "npx", + "args": [ + "-y", + "@upstash/context7-mcp@latest" + ] +} +``` +Setelah server MCP ditambahkan, Anda dapat dengan mudah terus menggunakannya. +
+ +
+Instal di Amazon Q Developer CLI + +Tambahkan ini ke file konfigurasi Amazon Q Developer CLI Anda. Lihat [dokumentasi Amazon Q Developer CLI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html) untuk detail lebih lanjut. +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +
+ +
+Instal di Qodo Gen + +Lihat [dokumentasi Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps) untuk detail lebih lanjut. +1. Buka panel obrolan Qodo Gen di VSCode atau IntelliJ. +2. Klik Hubungkan lebih banyak alat. +3. Klik + Tambah MCP baru. +4. Tambahkan konfigurasi berikut: +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` +
+ +
+Instal di JetBrains AI Assistant + +Lihat [Dokumentasi JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) untuk detail lebih lanjut. +1. Di IDE JetBrains pergi ke `Pengaturan` -> `Alat` -> `Asisten AI` -> `Protokol Konteks Model (MCP)` +2. Klik `+ Tambah`. +3. Klik pada `Perintah` di pojok kiri atas dialog dan pilih opsi Sebagai JSON dari daftar +4. Tambahkan konfigurasi ini dan klik `OK` +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +5. Klik `Terapkan` untuk menyimpan perubahan. +6. Dengan cara yang sama context7 dapat ditambahkan untuk JetBrains Junie di `Pengaturan` -> `Alat` -> `Junie` -> `Pengaturan MCP` +
+ +
+Instal di Warp + +Lihat [Dokumentasi Protokol Konteks Model Warp](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) untuk detail. +1. Navigasikan `Pengaturan` > `AI` > `Kelola server MCP`. +2. Tambahkan server MCP baru dengan mengklik tombol `+ Tambah`. +3. Tempel konfigurasi yang diberikan di bawah: +```json +{ + "Context7": { + "command": "npx", + "args": [ + "-y", + "@upstash/context7-mcp" + ], + "env": {}, + "working_directory": null, + "start_on_launch": true + } +} +``` +4. Klik `Simpan` untuk menerapkan perubahan. +
+ +
+Instal di Opencode + +Tambahkan ini ke file konfigurasi Opencode Anda. Lihat [dokumentasi MCP Opencode](https://opencode.ai/docs/mcp-servers) untuk info lebih lanjut. + +#### Koneksi Server Remote Opencode + +```json +"mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "enabled": true + } +} +``` + +#### Koneksi Server Lokal Opencode + +```json +{ + "mcp": { + "context7": { + "type": "local", + "command": ["npx", "-y", "@upstash/context7-mcp"], + "enabled": true + } + } +} +``` +
+ +
+Instal di Copilot Coding Agent + +## Menggunakan Context7 dengan Copilot Coding Agent +Tambahkan konfigurasi berikut ke bagian `mcp` file konfigurasi Copilot Coding Agent Anda Repositori->Pengaturan->Copilot->Coding agent->Konfigurasi MCP: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": [ + "query-docs", + "resolve-library-id" + ] + } + } +} +``` +Untuk informasi lebih lanjut, lihat [dokumentasi resmi GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). +
+ +
+Instal di Copilot CLI + +1. Buka file konfigurasi MCP Copilot CLI. Lokasinya adalah `~/.copilot/mcp-config.json` (di mana `~` adalah direktori home Anda). +2. Tambahkan yang berikut ke objek `mcpServers` di file `mcp-config.json` Anda: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Atau, untuk server lokal: +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +Jika file `mcp-config.json` tidak ada, buatlah. +
+ +
+Instal di Kiro + +Lihat [Dokumentasi Protokol Konteks Model Kiro](https://kiro.dev/docs/mcp/configuration/) untuk detail. +1. Navigasikan `Kiro` > `Server MCP` +2. Tambahkan server MCP baru dengan mengklik tombol `+ Tambah`. +3. Tempel konfigurasi yang diberikan di bawah: +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": [ + "-y", + "@upstash/context7-mcp" + ], + "env": {}, + "disabled": false, + "autoApprove": [] + } + } +} +``` +4. Klik `Simpan` untuk menerapkan perubahan. +
+ +
+Instal di OpenAI Codex + +Lihat [OpenAI Codex](https://github.com/openai/codex) untuk informasi lebih lanjut. +Tambahkan konfigurasi berikut ke pengaturan server MCP OpenAI Codex Anda: + +#### Koneksi Server Lokal + +```toml +[mcp_servers.context7] +args = ["-y", "@upstash/context7-mcp"] +command = "npx" +``` + +#### Koneksi Server Jarak Jauh + +```toml +[mcp_servers.context7] +url = "https://mcp.context7.com/mcp" +http_headers = { "CONTEXT7_API_KEY" = "YOUR_API_KEY" } +``` +
+ +
+Instal di LM Studio + +Lihat [Dukungan MCP LM Studio](https://lmstudio.ai/blog/lmstudio-v0.3.17) untuk informasi lebih lanjut. + +#### Instal satu klik: +[![Add MCP Server context7 to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB1cHN0YXNoL2NvbnRleHQ3LW1jcCJdfQ%3D%3D) + +#### Pengaturan manual: +1. Navigasikan ke `Program` (sisi kanan) > `Instal` > `Edit mcp.json`. +2. Tempel konfigurasi yang diberikan di bawah: +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +3. Klik `Simpan` untuk menerapkan perubahan. +4. Aktifkan/nonaktifkan server MCP dari sisi kanan, di bawah `Program`, atau dengan mengklik ikon colokan di bagian bawah kotak obrolan. +
+ +## 🔨 Alat yang Tersedia +Context7 MCP menyediakan alat berikut yang dapat digunakan oleh LLM: +- `resolve-library-id`: Mengubah nama pustaka umum menjadi ID pustaka yang kompatibel dengan Context7. + - `query` (wajib): Pertanyaan atau tugas pengguna (untuk peringkat relevansi) + - `libraryName` (wajib): Nama pustaka yang ingin dicari +- `query-docs`: Mengambil dokumentasi untuk pustaka menggunakan ID pustaka yang kompatibel dengan Context7. + - `libraryId` (wajib): ID pustaka yang kompatibel dengan Context7 (contoh: `/mongodb/docs`, `/vercel/next.js`) + - `query` (wajib): Pertanyaan atau tugas untuk mendapatkan dokumentasi yang relevan + +## 🛟 Tips + +### Tambahkan Aturan +> Jika Anda tidak ingin menambahkan `use context7` ke setiap permintaan, Anda dapat menentukan aturan sederhana di direktori `.devin/rules/` Anda di Devin Desktop atau dari bagian `Cursor Settings > Rules` di Cursor (atau yang setara di klien MCP Anda) untuk memanggil Context7 secara otomatis pada setiap pertanyaan kode: +> +> ```toml +> [[calls]] +> match = "when the user requests code examples, setup or configuration steps, or library/API documentation" +> tool = "context7" +> ``` +> +> Mulai saat itu, Anda akan mendapatkan dokumen Context7 dalam setiap percakapan terkait tanpa mengetik sesuatu tambahan. Anda dapat menambahkan kasus penggunaan Anda ke bagian match. + +### Gunakan ID Pustaka +> Jika Anda sudah tahu persis pustaka mana yang ingin digunakan, tambahkan ID Context7-nya ke permintaan Anda. Dengan begitu, server MCP Context7 dapat melewati langkah pencocokan pustaka dan langsung mengambil dokumen. +> +> ```txt +> implementasikan otentikasi dasar dengan supabase. gunakan pustaka /supabase/supabase untuk api dan docs +> ``` +> +> Sintaks garis miring memberi tahu alat MCP pustaka mana yang harus dimuat dokumennya. + +## 💻 Pengembangan +Salin proyek dan instal dependensi: +```bash +pnpm i +``` +Bangun: +```bash +pnpm run build +``` +Jalankan server: +```bash +node packages/mcp/dist/index.js +``` + +### Argumen CLI +`context7-mcp` menerima bendera CLI berikut: +- `--transport ` – Transportasi yang digunakan (`stdio` secara default). +- `--port ` – Port yang didengarkan saat menggunakan transport `http` (default `3000`). + Contoh dengan transport http dan port 8080: +```bash +node packages/mcp/dist/index.js --transport http --port 8080 +``` +
+Contoh Konfigurasi Lokal + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` +
+ +
+Pengujian dengan MCP Inspector + +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp +``` +
+ +## 🚨 Pemecahan Masalah +
+Kesalahan Modul Tidak Ditemukan + +Jika Anda mengalami `ERR_MODULE_NOT_FOUND`, coba gunakan `bunx` alih-alih `npx`: +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Ini sering menyelesaikan masalah penyelesaian modul di lingkungan di mana `npx` tidak menginstal atau menyelesaikan paket dengan benar. +
+ +
+Masalah Resolusi ESM + +Untuk kesalahan seperti `Error: Cannot find module 'uriTemplate.js'`, coba gunakan bendera `--experimental-vm-modules`: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` +
+ +
+Masalah TLS/Sertifikat + +Gunakan bendera `--experimental-fetch` untuk melewati masalah terkait TLS: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Kesalahan Umum Klien MCP + +1. Coba tambahkan `@latest` ke nama paket +2. Gunakan `bunx` sebagai alternatif `npx` +3. Pertimbangkan menggunakan `deno` sebagai alternatif lain +4. Pastikan Anda menggunakan Node.js v18 atau lebih tinggi untuk dukungan fetch native +
+ +## ⚠️ Penafian +Proyek Context7 dikontribusikan oleh komunitas dan meskipun kami berusaha menjaga kualitas tinggi, kami tidak dapat menjamin keakuratan, kelengkapan, atau keamanan semua dokumentasi pustaka. Proyek yang terdaftar di Context7 dikembangkan dan dikelola oleh pemilik masing-masing, bukan oleh Context7. Jika Anda menemukan konten yang mencurigakan, tidak pantas, atau berpotensi membahayakan, gunakan tombol "Laporkan" di halaman proyek untuk segera memberi tahu kami. Kami memperlakukan semua laporan dengan serius dan akan segera meninjau konten yang dilaporkan untuk menjaga integritas dan keamanan platform kami. Dengan menggunakan Context7, Anda mengakui bahwa Anda melakukannya atas kebijaksanaan dan risiko Anda sendiri. + +## 🤝 Terhubung dengan Kami +Tetap terbaru dan bergabunglah dengan komunitas kami: +- 📢 Ikuti kami di [X](https://x.com/context7ai) untuk berita dan pembaruan terbaru +- 🌐 Kunjungi [Situs Web](https://context7.com) kami +- 💬 Bergabunglah dengan [Komunitas Discord](https://upstash.com/discord) kami + +## 📺 Context7 Di Media +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ Sejarah Bintang +[![Star History Chart](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 Lisensi +MIT diff --git a/i18n/README.it.md b/i18n/README.it.md new file mode 100644 index 0000000..f716f10 --- /dev/null +++ b/i18n/README.it.md @@ -0,0 +1,331 @@ +# Context7 MCP - Documentazione aggiornata per qualsiasi prompt + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[![中文文档](https://img.shields.io/badge/docs-中文版-yellow)](./README.zh-CN.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentação em Português (Brasil)]()](./README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) + +## ❌ Senza Context7 + +LLMs si affidano a informazioni obsolete o generiche sulle librerie che utilizzi. Ottieni: + +- ❌ Gli esempi di codice sono obsoleti e basati su dati di formazione vecchi di anni +- ❌ Le API allucinate non esistono nemmeno +- ❌ Risposte generiche per vecchie versioni del pacchetto + +## ✅ Con Context7 + +Context7 MCP recupera documentazione aggiornata, specifica per versione e esempi di codice direttamente dalla fonte — e li inserisce direttamente nel tuo prompt. +Aggiungi `use context7` al prompt in Cursor: + +```txt +Crea un progetto Next.js di base con app router. Usa context7 +``` + +```txt +Creare uno script per eliminare le righe in cui la città è "", date le credenziali di PostgreSQL. usare context7 +``` + +Context7 recupera esempi di codice e documentazione aggiornati direttamente nel contesto del tuo LLM. + +- 1️⃣ Scrivi il tuo prompt in modo naturale +- 2️⃣ Indica all'LLM di usare context7 +- 3️⃣ Ottieni risposte di codice funzionante + Nessun cambio di tab, nessuna API allucinata che non esiste, nessuna generazione di codice obsoleta. + +## 🛠️ Iniziare + +### Requisiti + +- Node.js >= v18.0.0 +- Cursor, Devin Desktop, Claude Desktop o un altro client MCP + +### Installazione tramite Smithery + +Per installare Context7 MCP Server per Claude Desktop automaticamente tramite [Smithery](https://smithery.ai/server/@upstash/context7-mcp): + +```bash +npx -y @smithery/cli install @upstash/context7-mcp --client claude +``` + +### Installare in Cursor + +Vai a: `Impostazioni` -> `Impostazioni cursore` -> `MCP` -> `Aggiungi nuovo server MCP globale` +Incollare la seguente configurazione nel file `~/.cursor/mcp.json` di Cursor è l'approccio consigliato. Vedi [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) per ulteriori informazioni. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +
+Alternativa: Usa Bun + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +
+ +
+Alternativa: Usa Deno + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": ["run", "--allow-net", "npm:@upstash/context7-mcp"] + } + } +} +``` +
+ +### Installare in Devin Desktop +Aggiungi questo al tuo file di configurazione Devin Desktop MCP. Vedi [Devin Desktop MCP docs](https://docs.devin.ai/desktop/cascade/mcp) per ulteriori informazioni. +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Installare in VS Code +[Installa in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Installa in VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +Aggiungi questo al tuo file di configurazione MCP di VS Code. Vedi [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) per ulteriori informazioni. +```json +{ + "servers": { + "Context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Installare in Zed +Può essere installato tramite [Zed Extensions](https://zed.dev/extensions?query=Context7) oppure puoi aggiungere questo al tuo `settings.json` di Zed. Vedi [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) per ulteriori informazioni. +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +### Installare in Claude Code +Esegui questo comando. Vedi [Claude Code MCP docs](https://docs.anthropic.com/it/docs/claude-code/mcp) per ulteriori informazioni. +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest +``` + +### Installare in Claude Desktop +Aggiungi questo al tuo file `claude_desktop_config.json` di Claude Desktop. Vedi [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) per ulteriori informazioni. +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Installazione in Copilot Coding Agent +Aggiungi la seguente configurazione alla sezione `mcp` del file di configurazione di Copilot Coding Agent (Repository->Settings->Copilot->Coding agent->MCP configuration): +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Per maggiori informazioni, consulta la [documentazione ufficiale GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). + +### Installazione in Copilot CLI +1. Apri il file di configurazione MCP di Copilot CLI. La posizione è `~/.copilot/mcp-config.json` (dove `~` è la tua home directory). +2. Aggiungi quanto segue all'oggetto `mcpServers` nel tuo file `mcp-config.json`: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Oppure, per un server locale: +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +Se il file `mcp-config.json` non esiste, crealo. + +### Utilizzo di Docker +Se preferisci eseguire il server MCP in un contenitore Docker: +1. **Costruisci l'immagine Docker:** + Prima, crea un `Dockerfile` nella radice del progetto (o ovunque tu preferisca): +
+ Clicca per visualizzare il contenuto del Dockerfile + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # Installa l ultima versione globalmente + RUN npm install -g @upstash/context7-mcp@latest + # Esponi la porta predefinita se necessario (opzionale, dipende dall interazione del client MCP) + # EXPOSE 3000 + # Comando predefinito per eseguire il server + CMD ["context7-mcp"] + ``` +
+ + Poi, costruisci l'immagine utilizzando un tag (ad esempio, `context7-mcp`). **Assicurati che Docker Desktop (o il demone Docker) sia in esecuzione.** Esegui il seguente comando nella stessa directory in cui hai salvato il `Dockerfile`: + ```bash + docker build -t context7-mcp . + ``` +2. **Configura il tuo client MCP:** + Aggiorna la configurazione del tuo client MCP per utilizzare il comando Docker. + _Esempio per un file cline_mcp_settings.json:_ + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _Nota: Questa è una configurazione di esempio. Consulta gli esempi specifici per il tuo client MCP (come Cursor, VS Code, ecc.) precedentemente in questo README per adattare la struttura (ad es., `mcpServers` vs `servers`). Inoltre, assicurati che il nome dell'immagine in `args` corrisponda al tag utilizzato durante il comando `docker build`._ + +### Strumenti Disponibili +- `resolve-library-id`: Converte un nome generico di libreria in un ID di libreria compatibile con Context7. + - `query` (obbligatorio): La domanda o il compito dell'utente (per il ranking di rilevanza) + - `libraryName` (obbligatorio): Il nome della libreria da cercare +- `query-docs`: Recupera la documentazione per una libreria utilizzando un ID di libreria compatibile con Context7. + - `libraryId` (obbligatorio): ID esatto compatibile con Context7 (ad esempio, `/mongodb/docs`, `/vercel/next.js`) + - `query` (obbligatorio): La domanda o il compito per ottenere documentazione pertinente + +## Sviluppo +Clona il progetto e installa le dipendenze: +```bash +pnpm i +``` +Compila: +```bash +pnpm run build +``` + +### Esempio di Configurazione Locale +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` + +### Test con MCP Inspector +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp@latest +``` + +## Risoluzione dei problemi + +### ERR_MODULE_NOT_FOUND +Se vedi questo errore, prova a usare `bunx` invece di `npx`. +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +Questo spesso risolve i problemi di risoluzione dei moduli, specialmente negli ambienti dove `npx` non installa o risolve correttamente i pacchetti. + +### Problemi di risoluzione ESM +Se riscontri un errore come: `Error: Cannot find module 'uriTemplate.js'` prova a eseguire con il flag `--experimental-vm-modules`: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` + +### Errori del Client MCP +1. Prova a rimuovere `@latest` dal nome del pacchetto. +2. Prova a usare `bunx` come alternativa. +3. Prova a usare `deno` come alternativa. +4. Assicurati di utilizzare Node v18 o superiore per avere il supporto nativo di fetch con `npx`. + +## Dichiarazione di non responsabilità +I progetti Context7 sono contributi della comunità e, sebbene ci impegniamo a mantenere un'alta qualità, non possiamo garantire l'accuratezza, la completezza o la sicurezza di tutta la documentazione delle librerie. I progetti elencati in Context7 sono sviluppati e gestiti dai rispettivi proprietari, non da Context7. Se riscontri contenuti sospetti, inappropriati o potenzialmente dannosi, utilizza il pulsante "Segnala" sulla pagina del progetto per informarci immediatamente. Prendiamo sul serio tutte le segnalazioni e esamineremo prontamente i contenuti segnalati per mantenere l'integrità e la sicurezza della nostra piattaforma. Utilizzando Context7, riconosci di farlo a tua discrezione e a tuo rischio. + +## Context7 nei Media +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income stream surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income stream surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) + +## Storico delle Stelle +[![Star History Chart](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## Licenza +MIT diff --git a/i18n/README.ja.md b/i18n/README.ja.md new file mode 100644 index 0000000..0848965 --- /dev/null +++ b/i18n/README.ja.md @@ -0,0 +1,673 @@ +# Context7 MCP - どんなプロンプトにも最新のコードドキュメントで応える + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./README.zh-TW.md) [![簡體中文](https://img.shields.io/badge/docs-簡體中文-yellow)](./README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentação em Português (Brasil)]()](./README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./README.ru.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./README.ar.md) + +## ❌ Context7 を使わないと + +LLM は使用しているライブラリに関する古い情報や一般的な情報に依存しています。その結果： + +- ❌ コード例が古く、1 年前のトレーニングデータに基づいている +- ❌ 存在しない API をハルシネーションして生成する +- ❌ 古いパッケージバージョンに対する一般的な回答しか得られない + +## ✅ Context7 を使うと + +Context7 MCP は最新のバージョン固有のドキュメントとコード例をソースから直接取得し、プロンプトに直接配置します。 +Cursor のプロンプトに `use context7` を追加するだけ： + +```txt +Create a basic Next.js project with app router. use context7 +``` + +```txt +Create a script to delete the rows where the city is "" given PostgreSQL credentials. use context7 +``` + +Context7 は最新のコード例とドキュメントを直接 LLM のコンテキストに取得します。 + +- 1️⃣ 普段通りにプロンプトを書く +- 2️⃣ LLM に `use context7` と指示する +- 3️⃣ 動作するコードの回答を得る + タブの切り替えも、存在しない API のハルシネーションも、古いコード生成もありません。 + +## 📚 プロジェクトの追加 + +[プロジェクト追加ガイド](https://context7.com/docs/adding-libraries) をチェックして、お気に入りのライブラリを Context7 に追加（または更新）する方法を学びましょう。 + +## 🛠️ インストール + +### 必須要件 + +- Node.js >= v18.0.0 +- Cursor、Devin Desktop、Claude Desktop またはその他の MCP クライアント +
+Smithery 経由でのインストール + +[Smithery](https://smithery.ai/server/@upstash/context7-mcp) 経由で任意のクライアントに Context7 MCP サーバーを自動的にインストールするには： + +```bash +npx -y @smithery/cli@latest install @upstash/context7-mcp --client --key +``` + +Smithery キーは [Smithery.ai Web ページ](https://smithery.ai/server/@upstash/context7-mcp) で確認できます。 + +
+ +
+Cursor へのインストール + +`Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` に移動します +以下の設定を Cursor の `~/.cursor/mcp.json` ファイルに貼り付けることが推奨されます。プロジェクトフォルダに `.cursor/mcp.json` を作成することで、特定のプロジェクトにインストールすることもできます。詳細は [Cursor MCP ドキュメント](https://docs.cursor.com/context/model-context-protocol) を参照してください。 +> Cursor 1.0 以降、下のインストールボタンをクリックすることで、ワンクリックで即座にインストールできます。 + +#### Cursor リモートサーバー接続 +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Cursor ローカルサーバー接続 +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+代替方法：Bun を使用 + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoiYnVueCAteSBAdXBzdGFzaC9jb250ZXh0Ny1tY3AifQ%3D%3D) +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+代替方法：Deno を使用 + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoiZGVubyBydW4gLS1hbGxvdy1lbnYgLS1hbGxvdy1uZXQgbnBtOkB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": [ + "run", + "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", + "--allow-net", + "npm:@upstash/context7-mcp" + ] + } + } +} +``` +
+ +
+ +
+Devin Desktop へのインストール + +これを Devin Desktop MCP 設定ファイルに追加します。詳細は [Devin Desktop MCP ドキュメント](https://docs.devin.ai/desktop/cascade/mcp) を参照してください。 + +#### Devin Desktop リモートサーバー接続 + +```json +{ + "mcpServers": { + "context7": { + "serverUrl": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Devin Desktop ローカルサーバー接続 + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+VS Code へのインストール + +[Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Install in VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +これを VS Code MCP 設定ファイルに追加します。詳細は [VS Code MCP ドキュメント](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) を参照してください。 + +#### VS Code リモートサーバー接続 + +```json +"mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### VS Code ローカルサーバー接続 + +```json +"mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+ +Cline でのインストール + + +1. **Cline** を開きます。 +2. メニューアイコン (☰) をクリックし、**MCP サーバー**セクションに移動します。 +3. **リモートサーバー** タブを選択します。 +4. **設定を編集** ボタンをクリックします。 +5. context7 に関連する設定を `mcpServers` に追加します： +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp", + "type": "streamableHttp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` +
+ +
+Visual Studio 2022 へのインストール + +[Visual Studio MCP サーバードキュメント](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) に従って、Visual Studio 2022 で Context7 MCP を設定できます。 +これを Visual Studio MCP 設定ファイルに追加します（詳細は [Visual Studio ドキュメント](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) を参照）： +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } + } +} +``` +または、ローカルサーバーの場合： +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } + } +} +``` +詳細情報とトラブルシューティングについては、[Visual Studio MCP サーバードキュメント](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) を参照してください。 +
+ +
+Zed へのインストール + +[Zed Extensions](https://zed.dev/extensions?query=Context7) 経由でインストールできるか、Zed の `settings.json` にこれを追加できます。詳細は [Zed Context Server ドキュメント](https://zed.dev/docs/assistant/context-servers) を参照してください。 +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +
+ +
+Claude Code へのインストール + +このコマンドを実行します。詳細は [Claude Code MCP ドキュメント](https://docs.anthropic.com/ja/docs/claude-code/mcp) を参照してください。 + +#### Claude Code ローカルサーバー接続 + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp +``` + +#### Claude Code リモートサーバー接続 + +```sh +claude mcp add --scope user --transport http context7 https://mcp.context7.com/mcp +``` +
+ +
+Claude Desktop へのインストール + +これを Claude Desktop の `claude_desktop_config.json` ファイルに追加します。詳細は [Claude Desktop MCP ドキュメント](https://modelcontextprotocol.io/quickstart/user) を参照してください。 +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+BoltAI へのインストール + +アプリの "Settings" ページを開き、"Plugins" に移動し、以下の JSON を入力します： +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +保存後、チャットで `query-docs` の後に Context7 ドキュメント ID を入力します（例：`query-docs /nuxt/ui`）。詳細情報は [BoltAI ドキュメンテーションサイト](https://docs.boltai.com/docs/plugins/mcp-servers) で利用可能です。iOS 版 BoltAI については、[このガイドを参照してください](https://docs.boltai.com/docs/boltai-mobile/mcp-servers)。 +
+ +
+Copilot Coding Agent へのインストール + +以下の設定を Copilot Coding Agent の `mcp` セクション（Repository->Settings->Copilot->Coding agent->MCP configuration）に追加してください： +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +詳細は [公式 GitHub ドキュメント](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp) をご覧ください。 +
+ +
+Copilot CLI へのインストール + +1. Copilot CLI MCP 設定ファイルを開きます。ファイルの場所は `~/.copilot/mcp-config.json`（`~` はホームディレクトリ）です。 +2. `mcp-config.json` ファイルの `mcpServers` オブジェクトに以下を追加します： +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +または、ローカルサーバーの場合： +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +`mcp-config.json` ファイルが存在しない場合は、作成してください。 +
+ +
+Docker を使用 + +MCP サーバーを Docker コンテナで実行したい場合： +1. **Docker イメージのビルド：** + まず、プロジェクトルート（または希望の場所）に `Dockerfile` を作成します： +
+ Dockerfile の内容を表示 + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # 最新バージョンをグローバルにインストール + RUN npm install -g @upstash/context7-mcp + # 必要に応じてデフォルトポートを公開（任意、MCP クライアントの相互作用に依存） + # EXPOSE 3000 + # サーバーを実行するデフォルトコマンド + CMD ["context7-mcp"] + ``` +
+ + 次に、タグ（例：`context7-mcp`）を使用してイメージをビルドします。**Docker Desktop（または Docker デーモン）が実行中であることを確認してください。** `Dockerfile` を保存した同じディレクトリで次のコマンドを実行します： + ```bash + docker build -t context7-mcp . + ``` +2. **MCP クライアントの設定：** + MCP クライアントの設定を更新して Docker コマンドを使用するようにします。 + _cline_mcp_settings.json の例：_ + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _注：これは設定例です。この README の前半で MCP クライアント（Cursor、VS Code など）の具体的な例を参照して、構造（例：`mcpServers` 対 `servers`）を適応させてください。また、`args` 内のイメージ名が `docker build` コマンドで使用したタグと一致していることを確認してください。_ +
+ +
+Windows へのインストール + +Windows での設定は Linux や macOS と比べて少し異なります（_例では `Cline` を使用_）。同じ原則が他のエディタにも適用されます。`command` と `args` の設定を参照してください。 +```json +{ + "mcpServers": { + "github.com/upstash/context7-mcp": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"], + "disabled": false, + "autoApprove": [] + } + } +} +``` +
+ +
+Augment Code へのインストール + +Augment Code で Context7 MCP を設定するには、グラフィカルインターフェースまたは手動設定のいずれかを使用できます。 + +### **A. Augment Code UI を使用する場合** +1. ハンバーガーメニューをクリックします。 +2. **Settings** を選択します。 +3. **Tools** セクションに移動します。 +4. **+ Add MCP** ボタンをクリックします。 +5. 以下のコマンドを入力します： + ``` + npx -y @upstash/context7-mcp@latest + ``` +6. MCP に **Context7** と名前を付けます。 +7. **Add** ボタンをクリックします。 +MCP サーバーが追加されたら、Augment Code 内で Context7 の最新コードドキュメンテーション機能を直接使用できます。 +--- + +### **B. 手動設定** +1. Cmd/Ctrl Shift P を押すか、Augment パネルのハンバーガーメニューに移動します +2. Edit Settings を選択します +3. Advanced の下で、Edit in settings.json をクリックします +4. `augment.advanced` オブジェクト内の `mcpServers` 配列にサーバー設定を追加します +"augment.advanced": { +"mcpServers": [ +{ +"name": "context7", +"command": "npx", +"args": ["-y", "@upstash/context7-mcp"] +} +] +} +MCP サーバーが追加されたら、エディタを再起動します。エラーが発生した場合は、構文をチェックして、閉じ括弧やカンマが欠けていないことを確認してください。 +
+ +
+Roo Code へのインストール + +これを Roo Code MCP 設定ファイルに追加します。詳細は [Roo Code MCP ドキュメント](https://docs.roocode.com/features/mcp/using-mcp-in-roo) を参照してください。 + +#### Roo Code リモートサーバー接続 + +```json +{ + "mcpServers": { + "context7": { + "type": "streamable-http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Roo Code ローカルサーバー接続 + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Zencoder へのインストール + +Zencoder で Context7 MCP を設定するには、以下の手順に従います： +1. Zencoder メニュー (...) に移動します +2. ドロップダウンメニューから Agent tools を選択します +3. Add custom MCP をクリックします +4. 以下から名前とサーバー設定を追加し、Install ボタンを必ず押してください +```json +{ + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] +} +``` +MCP サーバーが追加されたら、簡単に使用を続けることができます。 +
+ +
+Amazon Q Developer CLI へのインストール + +これを Amazon Q Developer CLI 設定ファイルに追加します。詳細は [Amazon Q Developer CLI ドキュメント](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html) を参照してください。 +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +
+ +## 🔨 利用可能なツール +Context7 MCP は LLM が使用できる以下のツールを提供します： +- `resolve-library-id`：一般的なライブラリ名を Context7 互換のライブラリ ID に変換します。 + - `query`（必須）：ユーザーの質問またはタスク（関連性によるランキングに使用） + - `libraryName`（必須）：検索するライブラリの名前 +- `query-docs`：Context7 互換のライブラリ ID を使用してライブラリのドキュメントを取得します。 + - `libraryId`（必須）：正確な Context7 互換のライブラリ ID（例：`/mongodb/docs`、`/vercel/next.js`） + - `query`（必須）：関連するドキュメントを取得するための質問またはタスク + +## 💻 開発 +プロジェクトをクローンして依存関係をインストールします： +```bash +pnpm i +``` +ビルド： +```bash +pnpm run build +``` +サーバーを実行： +```bash +node packages/mcp/dist/index.js +``` + +### CLI 引数 +`context7-mcp` は以下の CLI フラグを受け付けます： +- `--transport ` – 使用するトランスポート（デフォルトは `stdio`）。 +- `--port ` – `http` トランスポート使用時にリッスンするポート（デフォルト `3000`）。 +http トランスポートとポート 8080 の例： +```bash +node packages/mcp/dist/index.js --transport http --port 8080 +``` +
+ローカル設定例 + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` +
+ +
+MCP Inspector でのテスト + +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp +``` +
+ +## 🚨 トラブルシューティング +
+モジュールが見つからないエラー + +`ERR_MODULE_NOT_FOUND` が発生した場合は、`npx` の代わりに `bunx` を使用してみてください： +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +これにより、`npx` がパッケージを正しくインストールまたは解決できない環境でのモジュール解決の問題が解決されることがあります。 +
+ +
+ESM 解決の問題 + +`Error: Cannot find module 'uriTemplate.js'` のようなエラーの場合は、`--experimental-vm-modules` フラグを試してください： +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` +
+ +
+TLS/証明書の問題 + +TLS 関連の問題を回避するには、`--experimental-fetch` フラグを使用します： +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+一般的な MCP クライアントエラー + +1. パッケージ名に `@latest` を追加してみる +2. `npx` の代替として `bunx` を使用する +3. 別の代替方法として `deno` の使用を検討する +4. ネイティブ fetch サポートのために Node.js v18 以上を使用していることを確認する +
+ +## ⚠️ 免責事項 +Context7 プロジェクトはコミュニティが貢献しているもので、高品質を維持するよう努めていますが、すべてのライブラリドキュメントの正確性、完全性、セキュリティを保証することはできません。Context7 にリストされているプロジェクトは、Context7 ではなく、それぞれの所有者によって開発および保守されています。疑わしい、不適切な、または潜在的に有害なコンテンツを発見した場合は、プロジェクトページの「報告」ボタンを使用して、すぐにお知らせください。私たちはすべての報告を真剣に受け止め、プラットフォームの整合性と安全性を維持するために、フラグが付けられたコンテンツを迅速にレビューします。Context7 を使用することにより、あなたは自己の裁量とリスクで使用することを認めます。 + +## 🤝 私たちとつながる +最新情報を入手し、コミュニティに参加しましょう： +- 📢 最新ニュースとアップデートのために [X](https://x.com/contextai) でフォローしてください +- 🌐 [Web サイト](https://context7.com) を訪問してください +- 💬 [Discord コミュニティ](https://upstash.com/discord) に参加してください + +## 📺 メディアでの Context7 +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ スター履歴 +[![Star History Chart](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 ライセンス +MIT diff --git a/i18n/README.ko.md b/i18n/README.ko.md new file mode 100644 index 0000000..006719e --- /dev/null +++ b/i18n/README.ko.md @@ -0,0 +1,227 @@ +![Cover](https://github.com/upstash/context7/blob/master/public/cover.png?raw=true) + +[![MCP 서버 설치](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) + +# Context7 MCP - 모든 프롬프트를 위한 최신 코드 문서 + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [![NPM Version](https://img.shields.io/npm/v/%40upstash%2Fcontext7-mcp?color=red)](https://www.npmjs.com/package/@upstash/context7-mcp) [![MIT licensed](https://img.shields.io/npm/l/%40upstash%2Fcontext7-mcp)](../LICENSE) + +[![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./README.zh-TW.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](./README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentação em Português (Brasil)]()](./README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./README.ru.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./README.uk.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./README.ar.md) [![Tiếng Việt](https://img.shields.io/badge/docs-Tiếng%20Việt-red)](./README.vi.md) + +## ❌ Context7 미사용 시 + +LLM은 사용하는 라이브러리에 대해 오래되거나 일반적인 정보에 의존하므로 다음과 같은 문제가 발생합니다: + +- ❌ 1년 전 학습 데이터를 기반으로 한 오래된 코드 예제 +- ❌ 실제로 존재하지 않는 API에 대한 환각(Hallucination) +- ❌ 구 버전 패키지에 대한 일반적인 답변 + +## ✅ Context7 사용 시 + +Context7 MCP는 소스에서 직접 최신 버전별 문서와 코드 예제를 가져와 프롬프트에 바로 배치합니다. + +프롬프트에 `use context7`을 추가하세요(또는 자동으로 호출되도록 [규칙을 설정](#규칙-추가)하세요): + +```txt +쿠키에서 유효한 JWT를 확인하고 인증되지 않은 사용자를 '/login'으로 리디렉션하는 Next.js 미들웨어를 만들어주세요. use context7 +``` + +```txt +JSON API 응답을 5분 동안 캐시하도록 Cloudflare Worker 스크립트를 구성해주세요. use context7 +``` + +Context7은 최신 코드 예제와 문서를 LLM의 컨텍스트로 바로 가져옵니다. 탭 전환도, 존재하지 않는 API에 대한 환각도, 오래된 코드 생성도 없습니다. + +## 설치 + +> [!NOTE] +> **API 키 권장**: 더 높은 속도 제한을 위해 [context7.com/dashboard](https://context7.com/dashboard)에서 무료 API 키를 받으세요. + +
+Cursor에 설치 + +이동: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` + +Cursor의 `~/.cursor/mcp.json` 파일에 다음 설정을 붙여넣는 것이 권장되는 접근 방식입니다. 프로젝트 폴더에 `.cursor/mcp.json`을 생성하여 특정 프로젝트에 설치할 수도 있습니다. 자세한 내용은 [Cursor MCP 문서](https://docs.cursor.com/context/model-context-protocol)를 참조하세요. + +> Cursor 1.0부터는 아래 설치 버튼을 클릭하여 즉시 원클릭 설치가 가능합니다. + +#### Cursor 원격 서버 연결 + +[![MCP 서버 설치](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Cursor 로컬 서버 연결 + +[![MCP 서버 설치](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Claude Code에 설치 + +이 명령어를 실행하세요. 자세한 내용은 [Claude Code MCP 문서](https://code.claude.com/docs/en/mcp)를 참조하세요. + +#### Claude Code 로컬 서버 연결 + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY +``` + +#### Claude Code 원격 서버 연결 + +```sh +claude mcp add --scope user --header "CONTEXT7_API_KEY: YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp +``` + +
+ +
+Opencode에 설치 + +Opencode 설정 파일에 이것을 추가하세요. 자세한 내용은 [Opencode MCP 문서](https://opencode.ai/docs/mcp-servers)를 참조하세요. + +#### Opencode 원격 서버 연결 + +```json +"mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "enabled": true + } +} +``` + +#### Opencode 로컬 서버 연결 + +```json +{ + "mcp": { + "context7": { + "type": "local", + "command": ["npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "enabled": true + } + } +} +``` + +
+ +**[기타 IDE 및 클라이언트 →](https://context7.com/docs/resources/all-clients)** + +## 중요 팁 + +### 규칙 추가 + +모든 프롬프트에 `use context7`을 입력하는 것을 피하려면, 코드 관련 질문에 대해 자동으로 Context7을 호출하도록 MCP 클라이언트에 규칙을 추가하세요: + +- **Cursor**: `Cursor Settings > Rules` +- **Claude Code**: `CLAUDE.md` +- 또는 사용 중인 MCP 클라이언트의 동등한 기능 + +**규칙 예시:** + +```txt +라이브러리/API 문서, 코드 생성, 설정 또는 구성 단계가 필요할 때 내가 명시적으로 요청하지 않아도 항상 Context7 MCP를 사용하세요. +``` + +### 라이브러리 ID 사용 + +사용하려는 라이브러리를 이미 정확히 알고 있다면, 프롬프트에 해당 라이브러리의 Context7 ID를 추가하세요. 이렇게 하면 Context7 MCP 서버가 라이브러리 매칭 단계를 건너뛰고 바로 문서 검색을 계속할 수 있습니다. + +```txt +Supabase로 기본 인증을 구현해줘. API와 문서는 use library /supabase/supabase를 사용해줘. +``` + +슬래시 구문은 MCP 도구에게 어떤 라이브러리의 문서를 로드할지 정확히 알려줍니다. + +### 버전 지정 + +특정 라이브러리 버전에 대한 문서를 얻으려면 프롬프트에 버전을 언급하면 됩니다: + +```txt +Next.js 14 미들웨어는 어떻게 설정하나요? use context7 +``` + +Context7은 적절한 버전을 자동으로 매칭합니다. + +## 사용 가능한 도구 + +Context7 MCP는 LLM이 사용할 수 있는 다음 도구들을 제공합니다: + +- `resolve-library-id`: 일반적인 라이브러리 이름을 Context7이 인식할 수 있는 라이브러리 ID로 변환합니다. + - `query` (필수): 사용자의 질문 또는 작업 (결과 순위 지정에 사용됨) + - `libraryName` (필수): 검색할 라이브러리의 이름 + +- `query-docs`: Context7 호환 라이브러리 ID를 사용하여 라이브러리의 문서를 가져옵니다. + - `libraryId` (필수): 정확한 Context7 호환 라이브러리 ID (예: `/mongodb/docs`, `/vercel/next.js`) + - `query` (필수): 관련 문서를 가져오기 위한 질문 또는 작업 + +## 추가 문서 + +- [더 많은 MCP 클라이언트](https://context7.com/docs/resources/all-clients) - 30개 이상의 클라이언트에 대한 설치 방법 +- [라이브러리 추가](https://context7.com/docs/adding-libraries) - Context7에 라이브러리 제출하기 +- [문제 해결](https://context7.com/docs/resources/troubleshooting) - 일반적인 문제 및 해결 방법 +- [API 참조](https://context7.com/docs/api-guide) - REST API 문서 +- [개발자 가이드](https://context7.com/docs/resources/developer) - 로컬에서 Context7 MCP 실행하기 + +## 면책 조항 + +1- Context7 프로젝트는 커뮤니티의 기여로 이루어지며 높은 품질을 유지하기 위해 노력하지만, 모든 라이브러리 문서의 정확성, 완전성 또는 보안을 보장할 수는 없습니다. Context7에 나열된 프로젝트는 Context7이 아닌 해당 소유자가 개발하고 유지 관리합니다. 의심스럽거나, 부적절하거나, 잠재적으로 유해한 콘텐츠를 발견하면 프로젝트 페이지의 "Report" 버튼을 사용하여 즉시 알려주시기 바랍니다. 저희는 모든 신고를 심각하게 받아들이며 플랫폼의 무결성과 안전을 유지하기 위해 신고된 콘텐츠를 신속하게 검토할 것입니다. Context7을 사용함으로써 귀하는 자신의 재량과 위험 감수 하에 사용함을 인정하는 것입니다. + +2- 이 저장소는 MCP 서버의 소스 코드를 호스팅합니다. API 백엔드, 파싱 엔진, 크롤링 엔진과 같은 지원 구성 요소는 비공개이며 이 저장소의 일부가 아닙니다. + +## 🤝 소통하기 + +최신 소식을 받고 커뮤니티에 참여하세요: + +- 📢 [X](https://x.com/context7ai)에서 팔로우하여 최신 뉴스 및 업데이트 확인 +- 🌐 [웹사이트](https://context7.com) 방문 +- 💬 [Discord 커뮤니티](https://upstash.com/discord) 참여 + +## 📺 미디어 속 Context7 + +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 라이선스 + +MIT diff --git a/i18n/README.pt-BR.md b/i18n/README.pt-BR.md new file mode 100644 index 0000000..c589582 --- /dev/null +++ b/i18n/README.pt-BR.md @@ -0,0 +1,1032 @@ +# Context7 MCP - Documentação de Código Atualizada para Qualquer Prompt + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) +[Instalar no Cursor](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) [Instalar no VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[![Documentation in English](https://img.shields.io/badge/docs-English-purple)](../README.md) [![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./README.zh-TW.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](./README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./README.ru.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./README.uk.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./README.ar.md) [![Tiếng Việt](https://img.shields.io/badge/docs-Tiếng%20Việt-red)](./README.vi.md) + +## ❌ Sem o Context7 + +Os LLMs dependem de informações desatualizadas ou genéricas sobre as bibliotecas que você usa. Você obtém: + +- ❌ Exemplos de código desatualizados e baseados em dados de treinamento de anos atrás +- ❌ APIs alucinadas que nem existem +- ❌ Respostas genéricas para versões antigas de pacotes + +## ✅ Com o Context7 + +O Context7 MCP extrai documentação e exemplos de código atualizados e específicos para cada versão diretamente da fonte — e os coloca diretamente em seu prompt. +Adicione `use context7` ao seu prompt no Cursor: + +```txt +Create a basic Next.js project with app router. use context7 +``` + +```txt +Create a script to delete the rows where the city is "" given PostgreSQL credentials. use context7 +``` + +O Context7 busca exemplos de código e documentação atualizados diretamente para o contexto do seu LLM. + +- 1️⃣ Escreva seu prompt naturalmente +- 2️⃣ Diga ao LLM `use context7` +- 3️⃣ Obtenha respostas com código funcional + Sem alternar entre abas, sem APIs alucinadas que não existem, sem gerações de código desatualizadas. + +## 📚 Adicionando Projetos + +Confira nosso [guia de adição de projetos](https://context7.com/docs/adding-libraries) para aprender como adicionar (ou atualizar) suas bibliotecas favoritas ao Context7. + +## 🛠️ Instalação + +### Requisitos + +- Node.js >= v18.0.0 +- Cursor, Claude Code, VSCode, Devin Desktop ou outro Cliente MCP +
+Instalando via Smithery + +Para instalar o Context7 MCP Server automaticamente em qualquer cliente via [Smithery](https://smithery.ai/server/@upstash/context7-mcp): + +```bash +npx -y @smithery/cli@latest install @upstash/context7-mcp --client --key +``` + +Você pode encontrar sua chave Smithery na [página do Smithery.ai](https://smithery.ai/server/@upstash/context7-mcp). + +
+ +
+Instalar no Cursor + +Vá em: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` +Colar a seguinte configuração no arquivo `~/.cursor/mcp.json` do Cursor é a abordagem recomendada. Você também pode instalar em um projeto específico criando `.cursor/mcp.json` na pasta do seu projeto. Veja mais em [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol). +> Desde o Cursor 1.0, você pode clicar no botão de instalar abaixo para uma instalação instantânea com um clique. + +#### Conexão Remota do Servidor Cursor +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Conexão Local do Servidor Cursor +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instalar no Claude Code + +Execute este comando. Veja mais em [Claude Code MCP docs](https://docs.anthropic.com/pt/docs/claude-code/mcp). + +#### Conexão Local do Servidor Claude Code + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp +``` + +#### Conexão Remota do Servidor Claude Code + +```sh +claude mcp add --scope user --transport http context7 https://mcp.context7.com/mcp +``` +
+ +
+Instalar no Devin Desktop + +Adicione isto ao arquivo de configuração MCP do Devin Desktop. Veja mais em [Devin Desktop MCP docs](https://docs.devin.ai/desktop/cascade/mcp). + +#### Conexão Remota do Servidor Devin Desktop + +```json +{ + "mcpServers": { + "context7": { + "serverUrl": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Conexão Local do Servidor Devin Desktop + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instalar no VS Code + +[Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Install in VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +Adicione isto ao arquivo de configuração MCP do VS Code. Veja mais em [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). + +#### Conexão Remota do Servidor VS Code + +```json +"mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Conexão Local do Servidor VS Code + +```json +"mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+ +Instalar no Cline + + +Você pode instalar o Context7 facilmente pelo [Cline MCP Server Marketplace](https://cline.bot/mcp-marketplace) seguindo estas instruções: +1. Abra o **Cline**. +2. Clique no ícone de menu (☰) para entrar na seção **MCP Servers**. +3. Use a barra de busca na aba **Marketplace** para encontrar _Context7_. +4. Clique no botão **Install**. +
+ +
+Instalar no Zed + +Pode ser instalado via [Zed Extensions](https://zed.dev/extensions?query=Context7) ou você pode adicionar isto ao seu `settings.json` do Zed. Veja mais em [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers). +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +
+ +
+Instalar no Augment Code + +Para configurar o Context7 MCP no Augment Code, você pode usar a interface gráfica ou a configuração manual. + +### **A. Usando a UI do Augment Code** +1. Clique no menu hambúrguer. +2. Selecione **Settings**. +3. Navegue até a seção **Tools**. +4. Clique no botão **+ Add MCP**. +5. Insira o seguinte comando: + ``` + npx -y @upstash/context7-mcp@latest + ``` +6. Nomeie o MCP: **Context7**. +7. Clique no botão **Add**. +Depois que o servidor MCP for adicionado, você pode começar a usar os recursos de documentação de código atualizada do Context7 diretamente no Augment Code. +--- + +### **B. Configuração Manual** +1. Pressione Cmd/Ctrl Shift P ou vá ao menu hambúrguer no painel do Augment +2. Selecione Edit Settings +3. Em Advanced, clique em Edit em settings.json +4. Adicione a configuração do servidor ao array `mcpServers` no objeto `augment.advanced` +```json +"augment.advanced": { + "mcpServers": [ + { + "name": "context7", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + ] +} +``` +Depois de adicionar o servidor MCP, reinicie seu editor. Se você receber algum erro, verifique a sintaxe para garantir que colchetes ou vírgulas não estejam faltando. +
+ +
+Instalar no Roo Code + +Adicione isto ao arquivo de configuração MCP do Roo Code. Veja mais em [Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo). + +#### Conexão Remota do Servidor Roo Code + +```json +{ + "mcpServers": { + "context7": { + "type": "streamable-http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Conexão Local do Servidor Roo Code + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instalar no Gemini CLI + +Veja os detalhes em [Configuração do Gemini CLI](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html). +1. Abra o arquivo de configurações do Gemini CLI. A localização é `~/.gemini/settings.json` (onde `~` é o seu diretório home). +2. Adicione o seguinte ao objeto `mcpServers` no seu arquivo `settings.json`: +```json +{ + "mcpServers": { + "context7": { + "httpUrl": "https://mcp.context7.com/mcp" + } + } +} +``` +Ou, para um servidor local: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Se o objeto `mcpServers` não existir, crie-o. +
+ +
+Instalar no Claude Desktop + +#### Conexão Remota +Abra o Claude Desktop e navegue até Settings > Connectors > Add Custom Connector. Insira o nome como `Context7` e a URL remota do MCP server como `https://mcp.context7.com/mcp`. + +#### Conexão Local +Abra as configurações de desenvolvedor do Claude Desktop e edite seu arquivo `claude_desktop_config.json` para adicionar a seguinte configuração. Veja mais em [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user). +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instalar no Opencode + +Adicione isto ao arquivo de configuração do Opencode. Veja mais em [Opencode MCP docs](https://opencode.ai/docs/mcp-servers). + +#### Conexão Remota do Opencode + +```json +"mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "enabled": true + } +} +``` + +#### Conexão Local do Opencode + +```json +{ + "mcp": { + "context7": { + "type": "local", + "command": ["npx", "-y", "@upstash/context7-mcp"], + "enabled": true + } + } +} +``` +
+ +
+Instalar no OpenAI Codex + +Veja mais em [OpenAI Codex](https://github.com/openai/codex). +Adicione a seguinte configuração às definições do servidor MCP do OpenAI Codex: + +#### Conexão de Servidor Local + +```toml +[mcp_servers.context7] +args = ["-y", "@upstash/context7-mcp"] +command = "npx" +``` + +#### Conexão de Servidor Remoto + +```toml +[mcp_servers.context7] +url = "https://mcp.context7.com/mcp" +http_headers = { "CONTEXT7_API_KEY" = "YOUR_API_KEY" } +``` +
+ +
+Instalar no JetBrains AI Assistant + +Veja mais detalhes na [Documentação do JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html). +1. Nos IDEs da JetBrains vá em `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)` +2. Clique em `+ Add`. +3. Clique em `Command` no canto superior esquerdo do diálogo e selecione a opção As JSON na lista +4. Adicione esta configuração e clique em `OK` +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +5. Clique em `Apply` para salvar as alterações. +6. Da mesma forma, o context7 pode ser adicionado ao JetBrains Junie em `Settings` -> `Tools` -> `Junie` -> `MCP Settings` +
+ +
+Instalar no Kiro + +Veja a [Documentação do Kiro Model Context Protocol](https://kiro.dev/docs/mcp/configuration/) para detalhes. +1. Navegue até `Kiro` > `MCP Servers` +2. Adicione um novo servidor MCP clicando no botão `+ Add`. +3. Cole a configuração abaixo: +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": {}, + "disabled": false, + "autoApprove": [] + } + } +} +``` +4. Clique em `Save` para aplicar as alterações. +
+ +
+Instalar no Trae + +Use o recurso Add manually e preencha as informações de configuração JSON para esse servidor MCP. +Para mais detalhes, visite a [documentação do Trae](https://docs.trae.ai/ide/model-context-protocol?_lang=en). + +#### Conexão Remota do Servidor Trae + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Conexão Local do Servidor Trae + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Usando Bun ou Deno + +Use estas alternativas para executar o servidor Context7 MCP local com outros runtimes. Esses exemplos funcionam para qualquer cliente que suporte iniciar um servidor MCP local via command + args. + +#### Bun + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +#### Deno + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": [ + "run", + "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", + "--allow-net", + "npm:@upstash/context7-mcp" + ] + } + } +} +``` +
+ +
+Usando Docker + +Se preferir executar o servidor MCP em um contêiner Docker: +1. **Crie a Imagem Docker:** + Primeiro, crie um `Dockerfile` na raiz do projeto (ou onde preferir): +
+ Clique para ver o conteúdo do Dockerfile + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # Instalar a versão mais recente globalmente + RUN npm install -g @upstash/context7-mcp + # Expor porta padrão se necessário (opcional, depende da interação do cliente MCP) + # EXPOSE 3000 + # Comando padrão para rodar o servidor + CMD ["context7-mcp"] + ``` +
+ + Em seguida, construa a imagem usando uma tag (por exemplo, `context7-mcp`). **Certifique-se de que o Docker Desktop (ou o daemon Docker) esteja em execução.** Execute o comando abaixo no mesmo diretório onde você salvou o `Dockerfile`: + ```bash + docker build -t context7-mcp . + ``` +2. **Configure seu Cliente MCP:** + Atualize a configuração do seu cliente MCP para usar o comando Docker. + _Exemplo para um cline_mcp_settings.json:_ + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _Nota: Este é um exemplo de configuração. Consulte os exemplos específicos do seu cliente MCP (como Cursor, VS Code, etc.) anteriormente neste README para adaptar a estrutura (por exemplo, `mcpServers` vs `servers`). Além disso, garanta que o nome da imagem em `args` corresponda à tag usada durante o comando `docker build`._ +
+ +
+Instalar Usando a Extensão Desktop + +Instale o arquivo [context7.dxt](dxt/context7.dxt) na pasta dxt e adicione-o ao seu cliente. Para mais informações, confira a [documentação de desktop extensions](https://github.com/anthropics/dxt#desktop-extensions-dxt). +
+ +
+Instalar no Windows + +A configuração no Windows é um pouco diferente em comparação ao Linux ou macOS (_`Cline` é usado no exemplo_). O mesmo princípio se aplica a outros editores; consulte a configuração de `command` e `args`. +```json +{ + "mcpServers": { + "github.com/upstash/context7-mcp": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp"], + "disabled": false, + "autoApprove": [] + } + } +} +``` +
+ +
+Instalar no Amazon Q Developer CLI + +Adicione isto ao arquivo de configuração do Amazon Q Developer CLI. Veja mais em [documentação do Amazon Q Developer CLI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html). +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instalar no Warp + +Veja mais em [Documentação do Warp Model Context Protocol](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). +1. Vá em `Settings` > `AI` > `Manage MCP servers`. +2. Adicione um novo servidor MCP clicando no botão `+ Add`. +3. Cole a configuração abaixo: +```json +{ + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": {}, + "working_directory": null, + "start_on_launch": true + } +} +``` +4. Clique em `Save` para aplicar as alterações. +
+ +
+Instalar no Copilot Coding Agent + +## Usando o Context7 com o Copilot Coding Agent +Adicione a seguinte configuração à seção `mcp` do arquivo de configuração do seu Copilot Coding Agent Repository->Settings->Copilot->Coding agent->MCP configuration: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Para mais informações, veja a [documentação oficial do GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). +
+ +
+Instalar no Copilot CLI + +1. Abra o arquivo de configuração MCP do Copilot CLI. A localização é `~/.copilot/mcp-config.json` (onde `~` é o seu diretório home). +2. Adicione o seguinte ao objeto `mcpServers` no seu arquivo `mcp-config.json`: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Ou, para um servidor local: +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +Se o arquivo `mcp-config.json` não existir, crie-o. +
+ +
+Instalar no LM Studio + +Veja mais em [Suporte a MCP no LM Studio](https://lmstudio.ai/blog/lmstudio-v0.3.17). + +#### Instalação com um clique: +[![Add MCP Server context7 to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB1cHN0YXNoL2NvbnRleHQ3LW1jcCJdfQ%3D%3D) + +#### Configuração manual: +1. Navegue até `Program` (lado direito) > `Install` > `Edit mcp.json`. +2. Cole a configuração abaixo: +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +3. Clique em `Save` para aplicar as alterações. +4. Ative/desative o servidor MCP no lado direito, em `Program`, ou clicando no ícone de plug na parte inferior da caixa de chat. +
+ +
+Instalar no Visual Studio 2022 + +Você pode configurar o Context7 MCP no Visual Studio 2022 seguindo a [documentação de MCP Servers do Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022). +Adicione isto ao arquivo de configuração MCP do Visual Studio (veja os [docs do Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) para detalhes): +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } + } +} +``` +Ou, para um servidor local: +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } + } +} +``` +Para mais informações e solução de problemas, consulte a [documentação de MCP Servers do Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022). +
+ +
+Instalar no Crush + +Adicione isto ao arquivo de configuração do Crush. Veja mais em [Crush MCP docs](https://github.com/charmbracelet/crush#mcps). + +#### Conexão Remota do Crush + +```json +{ + "$schema": "https://charm.land/crush.json", + "mcp": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Conexão Local do Crush + +```json +{ + "$schema": "https://charm.land/crush.json", + "mcp": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instalar no BoltAI + +Abra a página "Settings" do app, navegue até "Plugins" e insira o seguinte JSON: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Depois de salvar, digite no chat `query-docs` seguido do seu Context7 documentation ID (por exemplo, `query-docs /nuxt/ui`). Mais informações em [BoltAI's Documentation site](https://docs.boltai.com/docs/plugins/mcp-servers). Para o BoltAI no iOS, [veja este guia](https://docs.boltai.com/docs/boltai-mobile/mcp-servers). +
+ +
+Instalar no Rovo Dev CLI + +Edite sua configuração MCP do Rovo Dev CLI executando o comando abaixo - +```bash +acli rovodev mcp +``` +Configuração de exemplo - + +#### Conexão Remota + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Conexão Local + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Instalar no Zencoder + +Para configurar o Context7 MCP no Zencoder, siga estes passos: +1. Vá ao menu do Zencoder (...) +2. No menu suspenso, selecione Agent tools +3. Clique em Add custom MCP +4. Adicione o nome e a configuração do servidor abaixo e certifique-se de clicar no botão Install +```json +{ + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] +} +``` +Depois que o servidor MCP for adicionado, você pode continuar usando-o facilmente. +
+ +
+Instalar no Qodo Gen + +Veja mais em [docs do Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps). +1. Abra o painel de chat do Qodo Gen no VSCode ou IntelliJ. +2. Clique em Connect more tools. +3. Clique em + Add new MCP. +4. Adicione a seguinte configuração: + +#### Conexão Local do Qodo Gen + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +#### Conexão Remota do Qodo Gen + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` +
+ +
+Instalar no Perplexity Desktop + +Veja mais em [Local and Remote MCPs for Perplexity](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity). +1. Vá em `Perplexity` > `Settings` +2. Selecione `Connectors`. +3. Clique em `Add Connector`. +4. Selecione `Advanced`. +5. Insira Server Name: `Context7` +6. Cole o seguinte JSON na área de texto: +```json +{ + "args": ["-y", "@upstash/context7-mcp"], + "command": "npx", + "env": {} +} +``` +7. Clique em `Save`. +
+ +## 🔨 Ferramentas Disponíveis +O Context7 MCP fornece as seguintes ferramentas que LLMs podem usar: +- `resolve-library-id`: Resolve um nome geral de biblioteca em um ID compatível com o Context7. + - `query` (obrigatório): A pergunta ou tarefa do usuário (para ranking de relevância) + - `libraryName` (obrigatório): O nome da biblioteca a ser pesquisada +- `query-docs`: Busca documentação para uma biblioteca usando um ID compatível com o Context7. + - `libraryId` (obrigatório): ID exato compatível com Context7 (por exemplo, `/mongodb/docs`, `/vercel/next.js`) + - `query` (obrigatório): A pergunta ou tarefa para obter documentação relevante + +## 🛟 Dicas + +### Adicionar uma Regra +> Se você não quiser adicionar `use context7` a todo prompt, você pode definir uma regra simples no seu diretório `.devin/rules/` no Devin Desktop ou em `Cursor Settings > Rules` no Cursor (ou equivalente no seu cliente MCP) para invocar o Context7 automaticamente em qualquer questão de código: +> +> ```toml +> [[calls]] +> match = "quando o usuário solicitar exemplos de código, passos de configuração ou documentação de biblioteca/API" +> tool = "context7" +> ``` +> +> A partir daí você receberá os docs do Context7 em qualquer conversa relacionada sem digitar nada extra. Você pode adicionar seus casos de uso na parte match. + +### Usar o ID da Biblioteca +> Se você já sabe exatamente qual biblioteca deseja usar, adicione o ID do Context7 ao seu prompt. Assim, o servidor MCP do Context7 pode pular a etapa de correspondência de biblioteca e ir direto para recuperar os docs. +> +> ```txt +> implementar autenticação básica com supabase. use library /supabase/supabase para api e docs +> ``` +> +> A sintaxe com barra informa à ferramenta MCP exatamente qual biblioteca carregar. + +## 💻 Desenvolvimento +Clone o projeto e instale as dependências: +```bash +pnpm i +``` +Build: +```bash +pnpm run build +``` +Execute o servidor: +```bash +node packages/mcp/dist/index.js +``` + +### Argumentos de CLI +`context7-mcp` aceita as seguintes flags de CLI: +- `--transport ` – Transporte a ser usado (`stdio` por padrão). Use `http` para servidor HTTP remoto ou `stdio` para integração local. +- `--port ` – Porta para escutar ao usar o transporte `http` (padrão `3000`). +Exemplo com transporte http e porta 8080: +```bash +node packages/mcp/dist/index.js --transport http --port 8080 +``` +Outro exemplo com transporte stdio: +```bash +node packages/mcp/dist/index.js --transport stdio +``` +
+Exemplo de Configuração Local + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` +
+ +
+Testando com o MCP Inspector + +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp +``` +
+ +## 🚨 Solução de Problemas +
+Erros de Módulo Não Encontrado + +Se você encontrar `ERR_MODULE_NOT_FOUND`, tente usar `bunx` em vez de `npx`: +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Isso frequentemente resolve problemas de resolução de módulos em ambientes onde o `npx` não instala ou resolve os pacotes corretamente. +
+ +
+Problemas de Resolução ESM + +Para erros como `Error: Cannot find module 'uriTemplate.js'`, tente a flag `--experimental-vm-modules`: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` +
+ +
+Problemas de TLS/Certificados + +Use a flag `--experimental-fetch` para contornar problemas relacionados a TLS: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Erros Gerais do Cliente MCP + +1. Tente adicionar `@latest` ao nome do pacote +2. Use `bunx` como alternativa ao `npx` +3. Considere usar `deno` como outra alternativa +4. Certifique-se de estar usando Node.js v18 ou superior para suporte nativo a fetch +
+ +## ⚠️ Aviso +Os projetos do Context7 são contribuídos pela comunidade e, embora nos esforcemos para manter alta qualidade, não podemos garantir a precisão, integridade ou segurança de toda a documentação de bibliotecas. Os projetos listados no Context7 são desenvolvidos e mantidos por seus respectivos proprietários, não pelo Context7. Se você encontrar qualquer conteúdo suspeito, impróprio ou potencialmente prejudicial, use o botão "Report" na página do projeto para nos notificar imediatamente. Levamos todos os relatos a sério e revisaremos o conteúdo sinalizado prontamente para manter a integridade e a segurança de nossa plataforma. Ao usar o Context7, você reconhece que o faz por sua própria conta e risco. + +## 🤝 Conecte-se Conosco +Mantenha-se atualizado e junte-se à nossa comunidade: +- 📢 Siga-nos no [X](https://x.com/context7ai) para as últimas notícias e atualizações +- 🌐 Visite nosso [Website](https://context7.com) +- 💬 Junte-se ao nosso [Discord Community](https://upstash.com/discord) + +## 📺 Context7 na Mídia +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ Histórico de Stars +[![Gráfico de Histórico de Stars](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 Licença +MIT diff --git a/i18n/README.ru.md b/i18n/README.ru.md new file mode 100644 index 0000000..d879f4e --- /dev/null +++ b/i18n/README.ru.md @@ -0,0 +1,381 @@ +# Context7 MCP - Актуальная документация для любого промпта + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) + +## ❌ Без Context7 + +LLMs полагаются на устаревшую или обобщённую информацию о библиотеках, с которыми вы работаете. В результате этого вы получаете: + +- ❌ Устаревшие примеры кода многолетней давности +- ❌ Выдуманные API, которые даже не существуют +- ❌ Обобщённые ответы для старых библиотек + +## ✅ С Context7 + +Context7 MCP получает актуальную документацию и примеры кода, строго соответствующие нужной версии, прямо из исходных источников и вставляет их прямо в ваш промпт. +Добавьте строку `use context7` в промпт для Cursor: + +```txt +Создай базовый Next.js проект с маршрутизатором приложений. Use context7 +``` + +```txt +Создай скрипт, удаляющий строки, где город равен "", используя учётные данные PostgreSQL. Use context7 +``` + +Context7 MCP подгружает свежие примеры кода и документацию из источников прямо в контекст вашей LLM. + +- 1️⃣ Напишите свой промпт так, как писали его всегда +- 2️⃣ Добавьте к промпту `use context7` +- 3️⃣ Получите работающий результат + Никакого переключения между вкладками, выдуманного API или устаревшего кода. + +## 🛠️ Начало работы + +### Требования + +- Node.js >= v18.0.0 +- Cursor, Devin Desktop, Claude Desktop или другой MCP клиент + +### Установка через Smithery + +Воспользуйтесь [Smithery](https://smithery.ai/server/@upstash/context7-mcp), чтобы автоматически установить MCP сервер Context7 для Claude Desktop: + +```bash +npx -y @smithery/cli install @upstash/context7-mcp --client claude +``` + +### Установка в Cursor + +Перейдите в вкладку: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` +Рекомендуется вставить конфигурацию в файл `~/.cursor/mcp.json`. Также можно установить конфигурацию для конкретного проекта, создав файл `.cursor/mcp.json` в его директории. Смотрите [документацию Cursor MCP](https://docs.cursor.com/context/model-context-protocol) для получения дополнительной информации. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +
+Альтернативный вариант - Bun + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Альтернативный вариант - Deno + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": ["run", "--allow-env", "--allow-net", "npm:@upstash/context7-mcp"] + } + } +} +``` +
+ +### Установка в Devin Desktop +Добавьте следующие строки в ваш конфигурационный файл Devin Desktop MCP. Смотрите [документацию Devin Desktop MCP](https://docs.devin.ai/desktop/cascade/mcp) для получения дополнительной информации. +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +### Установка в VS Code +[Установка в VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Установка в VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +Добавьте следующие строки в ваш конфигурационный файл VS Code MCP. Смотрите [документацию VS Code MCP](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) для получения дополнительной информации. +```json +{ + "servers": { + "Context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +### Установка in Zed +Можно установить через [Zed расширение](https://zed.dev/extensions?query=Context7) или добавить следующие строки в `settings.json`. Смотрите [документацию Zed Context Server](https://zed.dev/docs/assistant/context-servers) для получения дополнительной информации. +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +### Установка в Claude Code +Запустите следующую команду для установки. Смотрите [документацию Claude Code MCP](https://docs.anthropic.com/ru/docs/claude-code/mcp) для получения дополнительной информации. +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp +``` + +### Установка в Claude Desktop +Добавьте следующие следующие строки в ваш конфигурационный файл `claude_desktop_config.json`. Смотрите [документацию Claude Desktop MCP](https://modelcontextprotocol.io/quickstart/user) для получения дополнительной информации. +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +### Установка в BoltAI +Откройте страницу "Settings", перейдите в "Plugins" и добавьте следующие JSON-строки: +```json +{ + "mcpServers": { + "context7": { + "args": ["-y", "@upstash/context7-mcp"], + "command": "npx" + } + } +} +``` + +### Установка в Copilot Coding Agent +Добавьте следующую конфигурацию в секцию `mcp` вашего файла настроек Copilot Coding Agent (Repository->Settings->Copilot->Coding agent->MCP configuration): +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Подробнее см. в [официальной документации GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). + +### Установка в Copilot CLI +1. Откройте файл конфигурации MCP Copilot CLI. Расположение: `~/.copilot/mcp-config.json` (где `~` — ваша домашняя папка). +2. Добавьте следующее к объекту `mcpServers` в вашем файле `mcp-config.json`: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Или для локального сервера: +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +Если файл `mcp-config.json` не существует, создайте его. + +### Используя Docker +Если вы предпочитаете запускать MCP сервер в Docker контейнере: +1. **Создайте образ Docker:** + Во-первых, создайте `Dockerfile` в корне вашего проекта (или в любом другом месте): +
+ Нажмите, чтобы просмотреть содержимое файла Dockerfile + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # Установите последнюю версию пакета глобально + RUN npm install -g @upstash/context7-mcp + # Откройте стандартный порт, если это необходимо (необязательно, это зависит от взаимодействия с MCP клиентом) + # EXPOSE 3000 + # Стандартная команда для запуска сервера + CMD ["context7-mcp"] + ``` +
+ + Затем, соберите образ, используя тег (например, `context7-mcp`). **Убедитесь, что Docker Desktop (или демон Docker) работает.** Запустите следующую команду в этой же директории, где сохранён `Dockerfile`: + ```bash + docker build -t context7-mcp . + ``` +2. **Настройте ваш MCP клиент:** + Обновите вашу конфигурацию MCP клиента, чтобы использовать Docker команду. + _Пример для cline_mcp_settings.json:_ + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _Примечение: это пример конфигурации. Обратитесь к конкретным примерам для вашего MCP-клиента (например, Cursor, VS Code и т.д.), в предыдущих разделах этого README, чтобы адаптировать структуру (например, `mcpServers` вместо `servers`). Также убедитесь, что имя образа в `args` соответствует тегу, использованному при выполнении команды `docker build`._ + +### Установка в Windows +Конфигурация в Windows немного отличается от Linux или macOS (_в качестве примера используется `Cline`_). Однако, эти же же принципы применимы и к другим редакторам. В случае необходимости обратитесь к настройкам `command` и `args`. +```json +{ + "mcpServers": { + "github.com/upstash/context7-mcp": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp"], + "disabled": false, + "autoApprove": [] + } + } +} +``` + +### Доступные инструменты +- `resolve-library-id`: преобразует общее название библиотеки в совместимый с Context7 идентификатор. + - `query` (обязательно): вопрос или задача пользователя (для ранжирования по релевантности) + - `libraryName` (обязательно): название библиотеки для поиска +- `query-docs`: получает документацию по библиотеке по совместимому с Context7 идентификатору. + - `libraryId` (обязательно): точный совместимый с Context7 идентификатор (например, `/mongodb/docs`, `/vercel/next.js`) + - `query` (обязательно): вопрос или задача для получения релевантной документации + +## Разработка +Склонируйте проект и установите зависимости: +```bash +pnpm i +``` +Сборка: +```bash +pnpm run build +``` + +### Пример локальной конфигурации +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` + +### Тестирование с помощью инспектора MCP +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp +``` + +## Решение проблем + +### ERR_MODULE_NOT_FOUND +Если вы видите эту ошибку, используйте `bunx` вместо `npx`. +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Зачастую это решает проблему с недостающими модулями, особенно в окружении, где `npx` некорректно устанавливает или разрешает библиотеки. + +### Проблемы с разрешением ESM +Если вы сталкиваетесь с проблемой по типу: `Error: Cannot find module 'uriTemplate.js'`, попробуйте запустить команду с флагом `--experimental-vm-modules`: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp"] + } + } +} +``` + +### Проблемы с TLS/сертификатами +Используйте флаг `--experimental-fetch` c `npx`, чтобы избежать ошибки, связанные с TLS: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"] + } + } +} +``` + +### Ошибки MCP клиента +1. Попробуйте добавить тег `@latest` в имя пакета. +2. Попробуйте использовать `bunx` как альтернативу `npx`. +3. Попробуйте использовать `deno` как замену `npx` или `bunx`. +4. Убедитесь, что используете версию Node v18 или выше, чтобы `npx` поддерживал встроенный `fetch`. + +## Отказ от ответственности +Проекты Context7 создаются сообществом. Мы стремимся поддерживать высокое качество, однако не можем гарантировать точность, полноту или безопасность всей документации по библиотекам. Проекты, представленные в Context7, разрабатываются и поддерживаются их авторами, а не командой Context7. +Если вы столкнётесь с подозрительным, неуместным или потенциально вредоносным контентом, пожалуйста, воспользуйтесь кнопкой "Report" на странице проекта, чтобы немедленно сообщить нам. Мы внимательно относимся ко всем обращениям и оперативно проверяем помеченные материалы, чтобы обеспечить надёжность и безопасность платформы. +Используя Context7, вы признаёте, что делаете это по собственному усмотрению и на свой страх и риск. + +## Оставайтесь с нами на связи +Будьте в курсе последних новостей на наших платформах: +- 📢 Следите за нашими новостями на [X](https://x.com/contextai), чтобы быть в курсе последних новостей +- 🌐 Загляните на наш [сайт](https://context7.com) +- 💬 При желании присоединяйтесь к нашему [сообществу в Discord](https://upstash.com/discord) + +## Context7 в СМИ +- [Better Stack: "Бесплатный инструмент делает Cursor в 10 раз умнее"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "Это, без сомнения, ЛУЧШИЙ MCP-сервер для AI-помощников в коде"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income stream surfers: "Context7 + SequentialThinking MCPs: Это уже AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: обновление MCP-агента"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: мгновенный доступ к документации + настройка для VS Code"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income stream surfers: "Context7: новый MCP-сервер, который изменит кодинг с ИИ"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: Этот MCP сервер делает CLINE в 100 раз ЭФФЕКТИВНЕЕ!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP серверов для стремительного вайб-программирования (Подключи и Работай)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## История звёзд на GitHub +[![График истории звёзд на GitHub](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## Лицензия +MIT diff --git a/i18n/README.tr.md b/i18n/README.tr.md new file mode 100644 index 0000000..bd97ffe --- /dev/null +++ b/i18n/README.tr.md @@ -0,0 +1,301 @@ +# Context7 MCP - Herhangi Bir Prompt İçin Güncel Kod Belgeleri + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [VS Code'da Yükle (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[![中文文档](https://img.shields.io/badge/docs-中文版-yellow)](./README.zh-CN.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentação em Português (Brasil)]()](./README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./README.ru.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./README.tr.md) + +## ❌ Context7 Olmadan + +LLM'ler, kullandığınız kütüphaneler hakkında güncel olmayan veya genel bilgilere güvenir. Karşılaştığınız sorunlar: + +- ❌ Kod örnekleri eskidir ve bir yıllık eğitim verilerine dayanır +- ❌ Halüsinasyon yapılan API'ler gerçekte mevcut değildir +- ❌ Eski paket sürümleri için genel cevaplar alırsınız + +## ✅ Context7 İle + +Context7 MCP, güncel ve sürüme özel belgeleri ve kod örneklerini doğrudan kaynağından çeker ve doğrudan prompt'unuza yerleştirir. +Cursor'da prompt'unuza `use context7` ekleyin: + +```txt +Next.js ile app router kullanan basit bir proje oluştur. use context7 +``` + +```txt +PostgreSQL kimlik bilgileriyle şehir değeri "" olan satırları silmek için bir betik oluştur. use context7 +``` + +Context7, güncel kod örneklerini ve belgelerini doğrudan LLM'inizin içeriğine getirir. + +- 1️⃣ Prompt'unuzu doğal bir şekilde yazın +- 2️⃣ LLM'e `use context7` kullanmasını söyleyin +- 3️⃣ Çalışan kod cevapları alın + Sekme değiştirme, var olmayan halüsinasyon API'ler, güncel olmayan kod üretimleri yok. + +## 🛠️ Başlangıç + +### Gereksinimler + +- Node.js >= v18.0.0 +- Cursor, Devin Desktop, Claude Desktop veya başka bir MCP İstemcisi + +### Smithery aracılığıyla kurulum + +Context7 MCP Server'ı Claude Desktop için [Smithery](https://smithery.ai/server/@upstash/context7-mcp) aracılığıyla otomatik olarak kurmak için: + +```bash +npx -y @smithery/cli install @upstash/context7-mcp --client claude +``` + +### Cursor'da Kurulum + +Şu yolu izleyin: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` +Aşağıdaki yapılandırmayı Cursor `~/.cursor/mcp.json` dosyanıza yapıştırmanız önerilen yaklaşımdır. Ayrıca, proje klasörünüzde `.cursor/mcp.json` oluşturarak belirli bir projeye de kurabilirsiniz. Daha fazla bilgi için [Cursor MCP belgelerine](https://docs.cursor.com/context/model-context-protocol) bakabilirsiniz. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +
+Alternatif: Bun Kullanın + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +
+ +
+Alternatif: Deno Kullanın + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": ["run", "--allow-net", "npm:@upstash/context7-mcp"] + } + } +} +``` +
+ +### Devin Desktop'te Kurulum +Bunu Devin Desktop MCP yapılandırma dosyanıza ekleyin. Daha fazla bilgi için [Devin Desktop MCP belgelerine](https://docs.devin.ai/desktop/cascade/mcp) bakabilirsiniz. +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### VS Code'da Kurulum +[VS Code'da Yükle (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[VS Code Insiders'da Yükle (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +Bunu VS Code MCP yapılandırma dosyanıza ekleyin. Daha fazla bilgi için [VS Code MCP belgelerine](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) bakabilirsiniz. +```json +{ + "servers": { + "Context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Zed'de Kurulum +[Zed Uzantıları](https://zed.dev/extensions?query=Context7) aracılığıyla kurulabilir veya Zed `settings.json` dosyanıza ekleyebilirsiniz. Daha fazla bilgi için [Zed Context Server belgelerine](https://zed.dev/docs/assistant/context-servers) bakabilirsiniz. +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +### Claude Code'da Kurulum +Bu komutu çalıştırın. Daha fazla bilgi için [Claude Code MCP belgelerine](https://docs.anthropic.com/en/docs/claude-code/mcp) bakabilirsiniz. +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest +``` + +### Claude Desktop'ta Kurulum +Bunu Claude Desktop `claude_desktop_config.json` dosyanıza ekleyin. Daha fazla bilgi için [Claude Desktop MCP belgelerine](https://modelcontextprotocol.io/quickstart/user) bakabilirsiniz. +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` + +### Copilot Coding Agent Kurulumu +Aşağıdaki yapılandırmayı Copilot Coding Agent'ın `mcp` bölümüne ekleyin (Repository->Settings->Copilot->Coding agent->MCP configuration): +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Daha fazla bilgi için [resmi GitHub dokümantasyonuna](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp) bakabilirsiniz. + +### Docker Kullanımı +MCP sunucusunu bir Docker konteynerinde çalıştırmayı tercih ederseniz: +1. **Docker Görüntüsü Oluşturun:** + Önce, proje kökünde (veya tercih ettiğiniz herhangi bir yerde) bir `Dockerfile` oluşturun: +
+ Dockerfile içeriğini görmek için tıklayın + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # En son sürümü global olarak yükleyin + RUN npm install -g @upstash/context7-mcp@latest + # Gerekirse varsayılan portu açın (isteğe bağlı, MCP istemci etkileşimine bağlıdır) + # EXPOSE 3000 + # Sunucuyu çalıştırmak için varsayılan komut + CMD ["context7-mcp"] + ``` +
+ + Ardından, bir etiket (örneğin, `context7-mcp`) kullanarak görüntüyü oluşturun. **Docker Desktop'un (veya Docker daemon'un) çalıştığından emin olun.** `Dockerfile`'ı kaydettiğiniz dizinde aşağıdaki komutu çalıştırın: + ```bash + docker build -t context7-mcp . + ``` +2. **MCP İstemcinizi Yapılandırın:** + MCP istemcinizin yapılandırmasını Docker komutunu kullanacak şekilde güncelleyin. + _cline_mcp_settings.json için örnek:_ + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _Not: Bu bir örnek yapılandırmadır. Yapıyı uyarlamak için MCP istemcinize (Cursor, VS Code vb.) özel örneklere bakın (örneğin, `mcpServers` ve `servers` farkı). Ayrıca, `args` içindeki görüntü adının `docker build` komutu sırasında kullanılan etiketle eşleştiğinden emin olun._ + +### Kullanılabilir Araçlar +- `resolve-library-id`: Genel bir kütüphane adını Context7 uyumlu bir kütüphane ID'sine dönüştürür. + - `query` (gerekli): Kullanıcının sorusu veya görevi (alaka sıralaması için) + - `libraryName` (gerekli): Aranacak kütüphane adı +- `query-docs`: Context7 uyumlu bir kütüphane ID'si kullanarak bir kütüphane için belgeleri getirir. + - `libraryId` (gerekli): Context7 uyumlu tam kütüphane ID'si (örneğin, `/mongodb/docs`, `/vercel/next.js`) + - `query` (gerekli): İlgili belgeleri almak için soru veya görev + +## Geliştirme +Projeyi klonlayın ve bağımlılıkları yükleyin: +```bash +pnpm i +``` +Derleyin: +```bash +pnpm run build +``` + +### Yerel Yapılandırma Örneği +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` + +### MCP Inspector ile Test Etme +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp@latest +``` + +## Sorun Giderme + +### ERR_MODULE_NOT_FOUND +Bu hatayı görürseniz, `npx` yerine `bunx` kullanmayı deneyin. +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +Bu, özellikle `npx`'in paketleri düzgün şekilde yüklemediği veya çözemediği ortamlarda modül çözümleme sorunlarını genellikle çözer. + +### ESM Çözümleme Sorunları +`Error: Cannot find module 'uriTemplate.js'` gibi bir hatayla karşılaşırsanız, `--experimental-vm-modules` bayrağıyla çalıştırmayı deneyin: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` + +### MCP İstemci Hataları +1. Paket adından `@latest` ifadesini kaldırmayı deneyin. +2. Alternatif olarak `bunx` kullanmayı deneyin. +3. Alternatif olarak `deno` kullanmayı deneyin. +4. `npx` ile yerel fetch desteğine sahip olmak için Node v18 veya daha yüksek bir sürüm kullandığınızdan emin olun. + +## Sorumluluk Reddi +Context7 projeleri topluluk katkılıdır ve yüksek kaliteyi korumaya çalışsak da, tüm kütüphane belgelerinin doğruluğunu, eksiksizliğini veya güvenliğini garanti edemeyiz. Context7'de listelenen projeler, Context7 tarafından değil, ilgili sahipleri tarafından geliştirilmekte ve sürdürülmektedir. Şüpheli, uygunsuz veya potansiyel olarak zararlı içerikle karşılaşırsanız, lütfen bizi hemen bilgilendirmek için proje sayfasındaki "Bildir" düğmesini kullanın. Tüm bildirimleri ciddiye alıyoruz ve platformumuzun bütünlüğünü ve güvenliğini korumak için işaretlenen içeriği hızla inceleyeceğiz. Context7'yi kullanarak, bunu kendi takdirinizle ve riskinizle yaptığınızı kabul etmiş olursunuz. + +## Context7 Medyada +- [Better Stack: "Ücretsiz Araç Cursor'u 10 Kat Daha Akıllı Yapıyor"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "Bu, Tartışmasız AI Kodlama Asistanları İçin EN İYİ MCP Sunucusudur"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income stream surfers: "Context7 + SequentialThinking MCP'leri: Bu AGI mi?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: Yeni MCP AI Aracı Güncellemesi"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Belgeleri Anında Alın + VS Code Kurulumu"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income stream surfers: "Context7: AI Kodlamayı DEĞİŞTİRECEK Yeni MCP Sunucusu"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: Bu MCP Sunucusu CLINE'ı 100 KAT DAHA ETKİLİ YAPIYOR!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "Vibe Kodlama İhtişamı İçin 5 MCP Sunucusu (Tak ve Çalıştır)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## Yıldız Geçmişi +[![Yıldız Geçmişi Grafiği](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## Lisans +MIT diff --git a/i18n/README.uk.md b/i18n/README.uk.md new file mode 100644 index 0000000..38b266a --- /dev/null +++ b/i18n/README.uk.md @@ -0,0 +1,825 @@ +# Context7 MCP — Актуальна документація з прикладами коду для будь-якого запиту + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./README.zh-TW.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](./README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentação em Português (Brasil)]()](./README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./README.ru.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./README.ar.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./README.uk.md) + +## ❌ Без Context7 + +Великі мовні моделі покладаються на застарілу або узагальнену інформацію про бібліотеки, які ви використовуєте. Внаслідок цього ви отримуєте: + +- ❌ Застарілі приклади коду, що базуються на даних навчання кількарічної давності +- ❌ «Галюцинації» — API, які взагалі не існують +- ❌ Узагальнені відповіді для старих версій пакунків + +## ✅ З Context7 + +Context7 MCP отримує актуальну, специфічну для версії документацію та приклади коду безпосередньо з джерела — і вбудовує їх прямо у ваш промпт. +Додайте `use context7` до вашого запиту в Cursor: + +```txt +Create a Next.js middleware that checks for a valid JWT in cookies and redirects unauthenticated users to `/login`. use context7 +``` + +```txt +Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7 +``` + +Context7 завантажує свіжі приклади коду й документацію безпосередньо в контекст вашої великої мовної моделі. + +- 1️⃣ Написуйте ваш промпт природно +- 2️⃣ Скажіть ШІ використати `use context7` +- 3️⃣ Отримайте робочі відповіді з кодом + Без перемикання між вкладками, без неіснуючих API та без застарілого коду. + +## 📚 Додавання проєктів + +Ознайомтеся з нашим [посібником з додавання проєктів](https://context7.com/docs/adding-libraries), щоб дізнатися, як додати (або оновити) ваші улюблені бібліотеки в Context7. + +## 🛠️ Встановлення + +### Системні вимоги + +- Node.js ≥ v18.0.0 +- Cursor, Devin Desktop, Claude Desktop або інший MCP-клієнт +
+Встановлення через Smithery + +Для автоматичного встановлення Context7 MCP Server для будь-якого клієнта через [Smithery](https://smithery.ai/server/@upstash/context7-mcp): + +```bash +npx -y @smithery/cli@latest install @upstash/context7-mcp --client --key +``` + +Ваш ключ Smithery можна знайти на [сторінці Smithery.ai](https://smithery.ai/server/@upstash/context7-mcp). + +
+ +
+Встановлення в Cursor + +Перейдіть до: `Settings` → `Cursor Settings` → `MCP` → `Add new global MCP server` +Рекомендується вставити наступну конфігурацію у файл `~/.cursor/mcp.json`. Також можна встановити для конкретного проєкту, створивши `.cursor/mcp.json` у теці проєкту. Детальніше див. у [документації Cursor MCP](https://docs.cursor.com/context/model-context-protocol). +> Починаючи з Cursor 1.0, ви можете просто натиснути кнопку встановлення нижче для миттєвої інсталяції. + +#### Підключення до віддаленого сервера Cursor +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Підключення до локального сервера Cursor +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+Альтернатива: використання Bun + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoiYnVueCAteSBAdXBzdGFzaC9jb250ZXh0Ny1tY3AifQ%3D%3D) +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Альтернатива: використання Deno + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoiZGVubyBydW4gLS1hbGxvdy1lbnYgLS1hbGxvdy1uZXQgbnBtOkB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": [ + "run", + "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", + "--allow-net", + "npm:@upstash/context7-mcp" + ] + } + } +} +``` +
+ +
+ +
+Встановлення в Devin Desktop + +Додайте це до вашого конфігураційного файлу Devin Desktop MCP. Детальніше див. у [документації Devin Desktop MCP](https://docs.devin.ai/desktop/cascade/mcp). + +#### Підключення до віддаленого сервера Devin Desktop + +```json +{ + "mcpServers": { + "context7": { + "serverUrl": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Підключення до локального сервера Devin Desktop + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Встановлення в Trae + +Використовуйте функцію "Add manually" і заповніть конфігурацію JSON для цього MCP-сервера. +Детальніше див. у [документації Trae](https://docs.trae.ai/ide/model-context-protocol?_lang=en). + +#### Підключення до віддаленого сервера Trae + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Підключення до локального сервера Trae + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Встановлення в VS Code + +[Встановити в VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Встановити в VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +Додайте це до вашого конфігураційного файлу VS Code MCP. Детальніше див. у [документації VS Code MCP](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). + +#### Підключення до віддаленого сервера VS Code + +```json +"mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Підключення до локального сервера VS Code + +```json +"mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Встановлення в Visual Studio 2022 + +Ви можете налаштувати Context7 MCP у Visual Studio 2022, дотримуючись [документації Visual Studio MCP Servers](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022). +Додайте це до вашого конфігураційного файлу Visual Studio MCP (детальніше в [документації Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022)): +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } + } +} +``` +Або для локального сервера: +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } + } +} +``` +
+ +
+Встановлення в Zed + +Можна встановити через [розширення Zed](https://zed.dev/extensions?query=Context7) або додати це до вашого `settings.json`. Детальніше див. у [документації Zed Context Server](https://zed.dev/docs/assistant/context-servers). +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +
+ +
+Встановлення в Copilot Coding Agent + +## Використання Context7 з Copilot Coding Agent +Додайте наступну конфігурацію до розділу `mcp` вашого файла настроек Copilot Coding Agent Repository->Settings->Copilot->Coding agent->MCP configuration: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Детальніше див. в [офіційній документації GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). +
+ +
+Встановлення в Copilot CLI + +1. Відкрийте файл конфігурації MCP Copilot CLI. Розташування: `~/.copilot/mcp-config.json` (де `~` — ваша домашня папка). +2. Додайте наступне до об'єкта `mcpServers` у вашому файлі `mcp-config.json`: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Або для локального сервера: +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +Якщо файл `mcp-config.json` не існує, створіть його. +
+ +
+Встановлення в Gemini CLI + +Детальніше див. у [конфігурації Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md). +1. Відкрийте файл налаштувань Gemini CLI. Розташування: `~/.gemini/settings.json` (де `~` — ваша домашня тека). +2. Додайте наступне до об'єкта `mcpServers` у вашому `settings.json`: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Якщо об'єкт `mcpServers` не існує, створіть його. +
+ +
+Встановлення в Claude Code + +Виконайте цю команду. Детальніше див. у [документації Claude Code MCP](https://docs.anthropic.com/en/docs/claude-code/mcp). + +#### Підключення до локального сервера Claude Code + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp +``` + +#### Підключення до віддаленого сервера Claude Code + +```sh +claude mcp add --scope user --transport http context7 https://mcp.context7.com/mcp +``` +
+ +
+Встановлення в Claude Desktop + +Додайте це до вашого файлу `claude_desktop_config.json` у Claude Desktop. Детальніше див. у [документації Claude Desktop MCP](https://modelcontextprotocol.io/quickstart/user). +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Встановлення в Cline + +Ви можете легко встановити Context7 через [торговий майданчик MCP-серверів Cline](https://cline.bot/mcp-marketplace), дотримуючись цих інструкцій: +1. Відкрийте **Cline**. +2. Натисніть значок меню гамбургер (☰), щоб увійти до розділу **MCP Servers**. +3. Використовуйте панель пошуку у вкладці **Marketplace**, щоб знайти _Context7_. +4. Натисніть кнопку **Install**. +
+ +
+Встановлення в BoltAI + +Відкрийте сторінку "Settings" застосунку, перейдіть до "Plugins" і введіть наступний JSON: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Після збереження введіть у чаті `query-docs`, а потім ваш ідентифікатор документації Context7 (наприклад, `query-docs /nuxt/ui`). Додаткова інформація доступна на [сайті документації BoltAI](https://docs.boltai.com/docs/plugins/mcp-servers). Для BoltAI на iOS [див. цей посібник](https://docs.boltai.com/docs/boltai-mobile/mcp-servers). +
+ +
+Використання Docker + +Якщо ви віддаєте перевагу запуску MCP-сервера в Docker-контейнері: +1. **Створіть Docker-образ:** + Спочатку створіть `Dockerfile` у корені проєкту (або де завгодно): +
+ Натисніть, щоб побачити вміст Dockerfile + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # Встановіть найновішу версію глобально + RUN npm install -g @upstash/context7-mcp + # Відкрийте стандартний порт, якщо потрібно (необов'язково, залежить від взаємодії з MCP-клієнтом) + # EXPOSE 3000 + # Стандартна команда для запуску сервера + CMD ["context7-mcp"] + ``` +
+ + Потім створіть образ, використовуючи тег (наприклад, `context7-mcp`). **Переконайтеся, що Docker Desktop (або демон Docker) запущений.** Виконайте наступну команду в тій же теці, де ви зберегли `Dockerfile`: + ```bash + docker build -t context7-mcp . + ``` +2. **Налаштуйте ваш MCP-клієнт:** + Оновіть конфігурацію вашого MCP-клієнта для використання Docker-команди. + _Приклад для cline_mcp_settings.json:_ + ```json + { + "mcpServers": { + "Context7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _Примітка: Це приклад конфігурації. Будь ласка, зверніться до конкретних прикладів для вашого MCP-клієнта (наприклад, Cursor, VS Code тощо) раніше в цьому README, щоб адаптувати структуру (наприклад, `mcpServers` проти `servers`). Також переконайтеся, що назва образу в `args` збігається з тегом, використаним під час команди `docker build`._ +
+ +
+Встановлення в Windows + +Конфігурація в Windows дещо відрізняється від Linux або macOS (_у прикладі використовується `Cline`_). Той же принцип застосовується до інших редакторів; зверніться до конфігурації `command` та `args`. +```json +{ + "mcpServers": { + "github.com/upstash/context7-mcp": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"], + "disabled": false, + "autoApprove": [] + } + } +} +``` +
+ +
+Встановлення в Augment Code + +Для налаштування Context7 MCP в Augment Code ви можете використовувати або графічний інтерфейс, або ручну конфігурацію. + +### **A. Використання інтерфейсу Augment Code** +1. Натисніть меню гамбургер. +2. Виберіть **Settings**. +3. Перейдіть до розділу **Tools**. +4. Натисніть кнопку **+ Add MCP**. +5. Введіть наступну команду: + ``` + npx -y @upstash/context7-mcp@latest + ``` +6. Назва MCP: **Context7**. +7. Натисніть кнопку **Add**. + +### **B. Ручна конфігурація** +1. Натисніть Cmd/Ctrl Shift P або перейдіть до меню гамбургер у панелі Augment +2. Виберіть Edit Settings +3. У розділі Advanced натисніть Edit in settings.json +4. Додайте конфігурацію сервера до масиву `mcpServers` в об'єкті `augment.advanced` +```json +"augment.advanced": { + "mcpServers": [ + { + "name": "context7", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + ] +} +``` +
+ +
+Встановлення в Roo Code + +Додайте це до вашого конфігураційного файлу Roo Code MCP. Детальніше див. у [документації Roo Code MCP](https://docs.roocode.com/features/mcp/using-mcp-in-roo). + +#### Підключення до віддаленого сервера Roo Code + +```json +{ + "mcpServers": { + "context7": { + "type": "streamable-http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Підключення до локального сервера Roo Code + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Встановлення в Zencoder + +Для налаштування Context7 MCP в Zencoder виконайте наступні кроки: +1. Перейдіть до меню Zencoder (...) +2. З випадного меню виберіть Agent tools +3. Натисніть на Add custom MCP +4. Додайте назву та конфігурацію сервера знизу і обов'язково натисніть кнопку Install +```json +{ + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] +} +``` +
+ +
+Встановлення в Amazon Q Developer CLI + +Додайте це до вашого конфігураційного файлу Amazon Q Developer CLI. Детальніше див. у [документації Amazon Q Developer CLI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html). +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +
+ +
+Встановлення в Qodo Gen + +Детальніше див. у [документації Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps). +1. Відкрийте панель чату Qodo Gen у VSCode або IntelliJ. +2. Натисніть Connect more tools. +3. Натисніть + Add new MCP. +4. Додайте наступну конфігурацію: +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` +
+ +
+Встановлення в JetBrains AI Assistant + +Детальніше див. у [документації JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html). +1. У JetBrains IDE перейдіть до `Settings` → `Tools` → `AI Assistant` → `Model Context Protocol (MCP)` +2. Натисніть `+ Add`. +3. Натисніть на `Command` у верхньому лівому куті діалогу та виберіть опцію As JSON зі списку +4. Додайте цю конфігурацію та натисніть `OK` +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +5. Натисніть `Apply`, щоб зберегти зміни. +
+ +
+Встановлення в Warp + +Детальніше див. у [документації Warp Model Context Protocol](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). +1. Перейдіть до `Settings` > `AI` > `Manage MCP servers`. +2. Додайте новий MCP-сервер, натиснувши кнопку `+ Add`. +3. Вставте конфігурацію, наведену нижче: +```json +{ + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": {}, + "working_directory": null, + "start_on_launch": true + } +} +``` +4. Натисніть `Save`, щоб застосувати зміни. +
+ +
+Встановлення в Opencode + +Додайте це до вашого конфігураційного файлу Opencode. Детальніше див. у [документації Opencode MCP](https://opencode.ai/docs/mcp-servers). + +#### Підключення до віддаленого сервера Opencode + +```json +"mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "enabled": true + } +} +``` + +#### Підключення до локального сервера Opencode + +```json +{ + "mcp": { + "context7": { + "type": "local", + "command": ["npx", "-y", "@upstash/context7-mcp"], + "enabled": true + } + } +} +``` +
+ +## 🔨 Доступні інструменти +Context7 MCP надає наступні інструменти, які можуть використовувати великі мовні моделі: +- `resolve-library-id`: Перетворює загальну назву бібліотеки на сумісний з Context7 ідентифікатор бібліотеки. + - `query` (обов'язково): Питання або завдання користувача (для ранжування за релевантністю) + - `libraryName` (обов'язково): Назва бібліотеки для пошуку +- `query-docs`: Отримує документацію для бібліотеки, використовуючи сумісний з Context7 ідентифікатор бібліотеки. + - `libraryId` (обов'язково): Точний сумісний з Context7 ідентифікатор бібліотеки (наприклад, `/mongodb/docs`, `/vercel/next.js`) + - `query` (обов'язково): Питання або завдання для отримання релевантної документації + +## 🛟 Поради + +### Додайте правило +> Якщо ви не хочете додавати `use context7` до кожного промпту, ви можете визначити просте правило у вашому каталозі `.devin/rules/` в Devin Desktop або в розділі `Cursor Settings > Rules` в Cursor (або еквівалентному у вашому MCP-клієнті), щоб автоматично викликати Context7 для будь-яких запитань про код: +> +> ```toml +> [[calls]] +> match = "when the user requests code examples, setup or configuration steps, or library/API documentation" +> tool = "context7" +> ``` +> +> Відтоді ви отримуватимете документацію Context7 у будь-якій пов'язаній розмові без введення будь-чого додаткового. Ви можете додати свої випадки використання до частини match. + +### Використовуйте ідентифікатор бібліотеки +> Якщо ви вже точно знаєте, яку бібліотеку хочете використовувати, додайте її ідентифікатор Context7 до вашого промпту. Таким чином Context7 MCP-сервер може пропустити крок пошуку бібліотеки та одразу перейти до отримання документації. +> +> ```txt +> implement basic authentication with supabase. use library /supabase/supabase for api and docs +> ``` +> +> Синтаксис із слешем повідомляє MCP-інструменту точно, для якої бібліотеки завантажувати документацію. + +## 💻 Розробка +Склонуйте проєкт і встановіть залежності: +```bash +pnpm i +``` +Збирання: +```bash +pnpm run build +``` +Запуск сервера: +```bash +node packages/mcp/dist/index.js +``` + +### Аргументи командного рядка +`context7-mcp` приймає наступні прапори CLI: +- `--transport ` — Транспорт для використання (`stdio` за замовчуванням). +- `--port ` — Порт для прослуховування при використанні транспорту `http` (за замовчуванням `3000`). +Приклад з http-транспортом і портом 8080: +```bash +node packages/mcp/dist/index.js --transport http --port 8080 +``` +
+Приклад локальної конфігурації + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` +
+ +
+Тестування з MCP Inspector + +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp +``` +
+ +## 🚨 Усунення несправностей +
+Помилки "Module Not Found" + +Якщо ви стикаєтеся з `ERR_MODULE_NOT_FOUND`, спробуйте використовувати `bunx` замість `npx`: +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Це часто вирішує проблеми розв'язання модулів у середовищах, де `npx` не встановлює або не розв'язує пакунки належним чином. +
+ +
+Проблеми розв'язання ESM + +Для помилок типу `Error: Cannot find module 'uriTemplate.js'` спробуйте прапор `--experimental-vm-modules`: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` +
+ +
+Проблеми TLS/сертифікатів + +Використовуйте прапор `--experimental-fetch`, щоб обійти проблеми, пов'язані з TLS: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Загальні помилки MCP-клієнта + +1. Спробуйте додати `@latest` до назви пакунка +2. Використовуйте `bunx` як альтернативу до `npx` +3. Розгляньте використання `deno` як іншу альтернативу +4. Переконайтеся, що ви використовуєте Node.js v18 або вище для підтримки нативного fetch +
+ +## ⚠️ Застереження +Проєкти Context7 створюються спільнотою, і хоча ми прагнемо підтримувати високу якість, ми не можемо гарантувати точність, повноту або безпеку всієї документації бібліотек. Проєкти, перелічені в Context7, розробляються та підтримуються їхніми відповідними власниками, а не Context7. Якщо ви зіткнетеся з будь-яким підозрілим, неприйнятним або потенційно шкідливим контентом, будь ласка, використовуйте кнопку "Report" на сторінці проєкту, щоб негайно повідомити нас. Ми серйозно ставимося до всіх звітів і оперативно переглядаємо позначений контент для підтримання цілісності та безпеки нашої платформи. Використовуючи Context7, ви визнаєте, що робите це на власний розсуд і ризик. + +## 🤝 Зв'яжіться з нами +Залишайтеся в курсі подій та приєднуйтеся до нашої спільноти: +- 📢 Слідкуйте за нами в [X](https://x.com/contextai) для отримання останніх новин та оновлень +- 🌐 Відвідайте наш [веб-сайт](https://context7.com) +- 💬 Приєднуйтеся до нашої [спільноти Discord](https://upstash.com/discord) + +## 📺 Context7 у медіа +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ Історія зірок +[![Діаграма історії зірок](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 Ліцензія +MIT diff --git a/i18n/README.vi.md b/i18n/README.vi.md new file mode 100644 index 0000000..83013a0 --- /dev/null +++ b/i18n/README.vi.md @@ -0,0 +1,909 @@ +# Context7 MCP - Tài Liệu Code Cập Nhật Cho Mọi Prompt + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./README.zh-TW.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](./README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentação em Português (Brasil)]()](./README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./README.ru.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./README.uk.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./README.ar.md) [![Tiếng Việt](https://img.shields.io/badge/docs-Tiếng%20Việt-red)](./README.vi.md) + +## ❌ Không có Context7 + +Các LLM dựa vào thông tin lỗi thời hoặc chung chung về các thư viện bạn sử dụng. Bạn sẽ gặp phải: + +- ❌ Các ví dụ code lỗi thời và dựa trên dữ liệu huấn luyện cũ +- ❌ API được tạo ra không tồn tại thực sự +- ❌ Câu trả lời chung chung cho các phiên bản package cũ + +## ✅ Với Context7 + +Context7 MCP lấy tài liệu và ví dụ code cập nhật, dành cho phiên bản cụ thể trực tiếp từ nguồn gốc — và đặt chúng trực tiếp vào prompt của bạn. +Thêm `use context7` vào prompt của bạn trong Cursor: + +```txt +Tạo một Next.js middleware kiểm tra JWT hợp lệ trong cookies và chuyển hướng người dùng chưa xác thực đến `/login`. use context7 +``` + +```txt +Cấu hình script Cloudflare Worker để cache JSON API responses trong năm phút. use context7 +``` + +Context7 lấy các ví dụ code và tài liệu cập nhật ngay vào context của LLM. + +- 1️⃣ Viết prompt một cách tự nhiên +- 2️⃣ Nói với LLM để `use context7` +- 3️⃣ Nhận được câu trả lời code hoạt động + Không cần chuyển tab, không có API tự tạo không tồn tại, không có code generation lỗi thời. + +## 📚 Thêm Dự Án + +Xem [hướng dẫn thêm dự án](https://context7.com/docs/adding-libraries) để học cách thêm (hoặc cập nhật) các thư viện yêu thích của bạn vào Context7. + +## 🛠️ Cài Đặt + +### Yêu Cầu + +- Node.js >= v18.0.0 +- Cursor, Devin Desktop, Claude Desktop hoặc MCP Client khác +
+Cài đặt qua Smithery + +Để cài đặt Context7 MCP Server cho bất kỳ client nào tự động qua [Smithery](https://smithery.ai/server/@upstash/context7-mcp): + +```bash +npx -y @smithery/cli@latest install @upstash/context7-mcp --client --key +``` + +Bạn có thể tìm Smithery key của mình tại [trang web Smithery.ai](https://smithery.ai/server/@upstash/context7-mcp). + +
+ +
+Cài đặt trong Cursor + +Đi đến: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` +Paste cấu hình sau vào file Cursor `~/.cursor/mcp.json` là cách được khuyến nghị. Bạn cũng có thể cài đặt trong một dự án cụ thể bằng cách tạo `.cursor/mcp.json` trong thư mục dự án. Xem [tài liệu Cursor MCP](https://docs.cursor.com/context/model-context-protocol) để biết thêm thông tin. +> Từ Cursor 1.0, bạn có thể click nút cài đặt bên dưới để cài đặt một cú click ngay lập tức. + +#### Kết nối Cursor Remote Server +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Kết nối Cursor Local Server +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+Thay thế: Sử dụng Bun + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoiYnVueCAteSBAdXBzdGFzaC9jb250ZXh0Ny1tY3AifQ%3D%3D) +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Thay thế: Sử dụng Deno + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=context7&config=eyJjb21tYW5kIjoiZGVubyBydW4gLS1hbGxvdy1lbnYgLS1hbGxvdy1uZXQgbnBtOkB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": [ + "run", + "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", + "--allow-net", + "npm:@upstash/context7-mcp" + ] + } + } +} +``` +
+ +
+ +
+Cài đặt trong Devin Desktop + +Thêm cấu hình này vào file cấu hình Devin Desktop MCP của bạn. Xem [tài liệu Devin Desktop MCP](https://docs.devin.ai/desktop/cascade/mcp) để biết thêm thông tin. + +#### Kết nối Devin Desktop Remote Server + +```json +{ + "mcpServers": { + "context7": { + "serverUrl": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Kết nối Devin Desktop Local Server + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Cài đặt trong Trae + +Sử dụng tính năng Add manually và điền thông tin cấu hình JSON cho MCP server đó. +Để biết thêm chi tiết, truy cập [tài liệu Trae](https://docs.trae.ai/ide/model-context-protocol?_lang=en). + +#### Kết nối Trae Remote Server + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Kết nối Trae Local Server + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Cài đặt trong VS Code + +[Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Install in VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +Thêm cấu hình này vào file cấu hình VS Code MCP của bạn. Xem [tài liệu VS Code MCP](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) để biết thêm thông tin. + +#### Kết nối VS Code Remote Server + +```json +"mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Kết nối VS Code Local Server + +```json +"mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Cài đặt trong Visual Studio 2022 + +Bạn có thể cấu hình Context7 MCP trong Visual Studio 2022 bằng cách làm theo [tài liệu Visual Studio MCP Servers](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022). +Thêm cấu hình này vào file cấu hình Visual Studio MCP của bạn (xem [tài liệu Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) để biết chi tiết): +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } + } +} +``` +Hoặc, cho local server: +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } + } +} +``` +Để biết thêm thông tin và khắc phục sự cố, tham khảo [tài liệu Visual Studio MCP Servers](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022). +
+ +
+Cài đặt trong Zed + +Có thể cài đặt thông qua [Zed Extensions](https://zed.dev/extensions?query=Context7) hoặc bạn có thể thêm cấu hình này vào `settings.json` của Zed. Xem [tài liệu Zed Context Server](https://zed.dev/docs/assistant/context-servers) để biết thêm thông tin. +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +
+ +
+Cài đặt trong Gemini CLI + +Xem [Cấu hình Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md) để biết chi tiết. +1. Mở file cài đặt Gemini CLI. Vị trí là `~/.gemini/settings.json` (trong đó `~` là thư mục home của bạn). +2. Thêm cấu hình sau vào object `mcpServers` trong file `settings.json` của bạn: +```json +{ + "mcpServers": { + "context7": { + "httpUrl": "https://mcp.context7.com/mcp" + } + } +} +``` +Hoặc, cho local server: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Nếu object `mcpServers` không tồn tại, hãy tạo nó. +
+ +
+Cài đặt trong Claude Code + +Chạy lệnh này. Xem [tài liệu Claude Code MCP](https://docs.anthropic.com/en/docs/claude-code/mcp) để biết thêm thông tin. + +#### Kết nối Claude Code Local Server + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp +``` + +#### Kết nối Claude Code Remote Server + +```sh +claude mcp add --scope user --transport http context7 https://mcp.context7.com/mcp +``` +
+ +
+Cài đặt trong Claude Desktop + +Thêm cấu hình này vào file `claude_desktop_config.json` của Claude Desktop. Xem [tài liệu Claude Desktop MCP](https://modelcontextprotocol.io/quickstart/user) để biết thêm thông tin. +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+ +Cài đặt trong Cline + + +Bạn có thể dễ dàng cài đặt Context7 thông qua [Cline MCP Server Marketplace](https://cline.bot/mcp-marketplace) bằng cách làm theo các hướng dẫn này: +1. Mở **Cline**. +2. Click biểu tượng menu hamburger (☰) để vào phần **MCP Servers**. +3. Sử dụng thanh tìm kiếm trong tab **Marketplace** để tìm _Context7_. +4. Click nút **Install**. +
+ +
+Cài đặt trong BoltAI + +Mở trang "Settings" của ứng dụng, điều hướng đến "Plugins," và nhập JSON sau: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Sau khi lưu, nhập trong chat `query-docs` theo sau bởi Context7 documentation ID của bạn (ví dụ: `query-docs /nuxt/ui`). Thêm thông tin có sẵn tại [trang Tài liệu BoltAI](https://docs.boltai.com/docs/plugins/mcp-servers). Cho BoltAI trên iOS, [xem hướng dẫn này](https://docs.boltai.com/docs/boltai-mobile/mcp-servers). +
+ +
+Sử dụng Docker + +Nếu bạn muốn chạy MCP server trong Docker container: +1. **Build Docker Image:** + Đầu tiên, tạo `Dockerfile` trong thư mục gốc dự án (hoặc bất cứ đâu bạn thích): +
+ Click để xem nội dung Dockerfile + + ```Dockerfile + FROM node:18-alpine + WORKDIR /app + # Cài đặt phiên bản mới nhất globally + RUN npm install -g @upstash/context7-mcp + # Expose default port nếu cần (tùy chọn, phụ thuộc vào tương tác MCP client) + # EXPOSE 3000 + # Lệnh mặc định để chạy server + CMD ["context7-mcp"] + ``` +
+ + Sau đó, build image sử dụng tag (ví dụ: `context7-mcp`). **Đảm bảo Docker Desktop (hoặc Docker daemon) đang chạy.** Chạy lệnh sau trong cùng thư mục nơi bạn lưu `Dockerfile`: + ```bash + docker build -t context7-mcp . + ``` +2. **Cấu hình MCP Client của bạn:** + Cập nhật cấu hình MCP client của bạn để sử dụng lệnh Docker. + _Ví dụ cho cline_mcp_settings.json:_ + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + _Lưu ý: Đây là một ví dụ cấu hình. Vui lòng tham khảo các ví dụ cụ thể cho MCP client của bạn (như Cursor, VS Code, v.v.) ở phần trước trong README này để điều chỉnh cấu trúc (ví dụ: `mcpServers` vs `servers`). Ngoài ra, đảm bảo tên image trong `args` khớp với tag được sử dụng trong lệnh `docker build`._ +
+ +
+Cài đặt trong Windows + +Cấu hình trên Windows hơi khác so với Linux hoặc macOS (_`Cline` được sử dụng trong ví dụ_). Nguyên tắc tương tự áp dụng cho các editor khác; tham khảo cấu hình của `command` và `args`. +```json +{ + "mcpServers": { + "github.com/upstash/context7-mcp": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"], + "disabled": false, + "autoApprove": [] + } + } +} +``` +
+ +
+Cài đặt trong Augment Code + +Để cấu hình Context7 MCP trong Augment Code, bạn có thể sử dụng giao diện đồ họa hoặc cấu hình thủ công. + +### **A. Sử dụng Augment Code UI** +1. Click menu hamburger. +2. Chọn **Settings**. +3. Điều hướng đến phần **Tools**. +4. Click nút **+ Add MCP**. +5. Nhập lệnh sau: + ``` + npx -y @upstash/context7-mcp@latest + ``` +6. Đặt tên MCP: **Context7**. +7. Click nút **Add**. +Sau khi MCP server được thêm, bạn có thể bắt đầu sử dụng các tính năng tài liệu code cập nhật của Context7 trực tiếp trong Augment Code. +--- + +### **B. Cấu hình Thủ công** +1. Nhấn Cmd/Ctrl Shift P hoặc đi đến menu hamburger trong panel Augment +2. Chọn Edit Settings +3. Trong Advanced, click Edit in settings.json +4. Thêm cấu hình server vào mảng `mcpServers` trong object `augment.advanced` +"augment.advanced": { +"mcpServers": [ +{ +"name": "context7", +"command": "npx", +"args": ["-y", "@upstash/context7-mcp"] +} +] +} +Sau khi MCP server được thêm, khởi động lại editor của bạn. Nếu bạn nhận được bất kỳ lỗi nào, kiểm tra cú pháp để đảm bảo không thiếu dấu ngoặc đóng hoặc dấu phẩy. +
+ +
+Cài đặt trong Roo Code + +Thêm cấu hình này vào file cấu hình Roo Code MCP của bạn. Xem [tài liệu Roo Code MCP](https://docs.roocode.com/features/mcp/using-mcp-in-roo) để biết thêm thông tin. + +#### Kết nối Roo Code Remote Server + +```json +{ + "mcpServers": { + "context7": { + "type": "streamable-http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Kết nối Roo Code Local Server + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Cài đặt trong Zencoder + +Để cấu hình Context7 MCP trong Zencoder, làm theo các bước sau: +1. Đi đến menu Zencoder (...) +2. Từ menu dropdown, chọn Agent tools +3. Click vào Add custom MCP +4. Thêm tên và cấu hình server từ bên dưới, và đảm bảo nhấn nút Install +```json +{ + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] +} +``` +Sau khi MCP server được thêm, bạn có thể dễ dàng tiếp tục sử dụng nó. +
+ +
+Cài đặt trong Amazon Q Developer CLI + +Thêm cấu hình này vào file cấu hình Amazon Q Developer CLI của bạn. Xem [tài liệu Amazon Q Developer CLI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html) để biết thêm chi tiết. +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } + } +} +``` +
+ +
+Cài đặt trong Qodo Gen + +Xem [tài liệu Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps) để biết thêm chi tiết. +1. Mở panel chat Qodo Gen trong VSCode hoặc IntelliJ. +2. Click Connect more tools. +3. Click + Add new MCP. +4. Thêm cấu hình sau: +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` +
+ +
+Cài đặt trong JetBrains AI Assistant + +Xem [Tài liệu JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) để biết thêm chi tiết. +1. Trong JetBrains IDEs đi đến `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)` +2. Click `+ Add`. +3. Click vào `Command` ở góc trên bên trái của dialog và chọn tùy chọn As JSON từ danh sách +4. Thêm cấu hình này và click `OK` +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +5. Click `Apply` để lưu thay đổi. +6. Theo cách tương tự, context7 có thể được thêm cho JetBrains Junie trong `Settings` -> `Tools` -> `Junie` -> `MCP Settings` +
+ +
+Cài đặt trong Warp + +Xem [Tài liệu Warp Model Context Protocol](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) để biết chi tiết. +1. Điều hướng `Settings` > `AI` > `Manage MCP servers`. +2. Thêm MCP server mới bằng cách click nút `+ Add`. +3. Paste cấu hình được cung cấp bên dưới: +```json +{ + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": {}, + "working_directory": null, + "start_on_launch": true + } +} +``` +4. Click `Save` để áp dụng thay đổi. +
+ +
+Cài đặt trong Opencode + +Thêm cấu hình này vào file cấu hình Opencode của bạn. Xem [tài liệu Opencode MCP](https://opencode.ai/docs/mcp-servers) để biết thêm thông tin. + +#### Kết nối Opencode Remote Server + +```json +"mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "enabled": true + } +} +``` + +#### Kết nối Opencode Local Server + +```json +{ + "mcp": { + "context7": { + "type": "local", + "command": ["npx", "-y", "@upstash/context7-mcp"], + "enabled": true + } + } +} +``` +
+ +
+Cài đặt trong Copilot Coding Agent + +## Sử dụng Context7 với Copilot Coding Agent +Thêm cấu hình sau vào phần `mcp` trong file cấu hình Copilot Coding Agent của bạn Repository->Settings->Copilot->Coding agent->MCP configuration: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Để biết thêm thông tin, xem [tài liệu GitHub chính thức](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). +
+ +
+Cài đặt trong Copilot CLI + +1. Mở file cấu hình MCP của Copilot CLI. Vị trí là `~/.copilot/mcp-config.json` (trong đó `~` là thư mục home của bạn). +2. Thêm nội dung sau vào đối tượng `mcpServers` trong file `mcp-config.json` của bạn: +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["query-docs", "resolve-library-id"] + } + } +} +``` +Hoặc, đối với server cục bộ: +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["query-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` +Nếu file `mcp-config.json` không tồn tại, hãy tạo nó. +
+ +
+Cài đặt trong Kiro + +Xem [Tài liệu Kiro Model Context Protocol](https://kiro.dev/docs/mcp/configuration/) để biết chi tiết. +1. Điều hướng `Kiro` > `MCP Servers` +2. Thêm MCP server mới bằng cách click nút `+ Add`. +3. Paste cấu hình được cung cấp bên dưới: +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": {}, + "disabled": false, + "autoApprove": [] + } + } +} +``` +4. Click `Save` để áp dụng thay đổi. +
+ +
+Cài đặt trong OpenAI Codex + +Xem [OpenAI Codex](https://github.com/openai/codex) để biết thêm thông tin. +Thêm cấu hình sau vào cài đặt OpenAI Codex MCP server của bạn: + +#### Kết nối Server Cục bộ + +```toml +[mcp_servers.context7] +args = ["-y", "@upstash/context7-mcp"] +command = "npx" +``` + +#### Kết nối Server Từ xa + +```toml +[mcp_servers.context7] +url = "https://mcp.context7.com/mcp" +http_headers = { "CONTEXT7_API_KEY" = "YOUR_API_KEY" } +``` +
+ +
+Cài đặt trong LM Studio + +Xem [LM Studio MCP Support](https://lmstudio.ai/blog/lmstudio-v0.3.17) để biết thêm thông tin. + +#### Cài đặt một cú click: +[![Add MCP Server context7 to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB1cHN0YXNoL2NvbnRleHQ3LW1jcCJdfQ%3D%3D) + +#### Thiết lập thủ công: +1. Điều hướng đến `Program` (bên phải) > `Install` > `Edit mcp.json`. +2. Paste cấu hình được cung cấp bên dưới: +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +3. Click `Save` để áp dụng thay đổi. +4. Bật/tắt MCP server từ bên phải, dưới `Program`, hoặc bằng cách click biểu tượng plug ở cuối hộp chat. +
+ +## 🔨 Công Cụ Có Sẵn +Context7 MCP cung cấp các công cụ sau mà LLM có thể sử dụng: +- `resolve-library-id`: Chuyển đổi tên thư viện chung thành Context7-compatible library ID. + - `query` (bắt buộc): Câu hỏi hoặc nhiệm vụ của người dùng (để xếp hạng độ liên quan) + - `libraryName` (bắt buộc): Tên của thư viện cần tìm kiếm +- `query-docs`: Lấy tài liệu cho thư viện sử dụng Context7-compatible library ID. + - `libraryId` (bắt buộc): Context7-compatible library ID chính xác (ví dụ: `/mongodb/docs`, `/vercel/next.js`) + - `query` (bắt buộc): Câu hỏi hoặc nhiệm vụ để lấy tài liệu liên quan + +## 🛟 Mẹo + +### Thêm Quy Tắc +> Nếu bạn không muốn thêm `use context7` vào mỗi prompt, bạn có thể định nghĩa một quy tắc đơn giản trong thư mục `.devin/rules/` của bạn trong Devin Desktop hoặc từ phần `Cursor Settings > Rules` trong Cursor (hoặc tương đương trong MCP client của bạn) để tự động gọi Context7 trên bất kỳ câu hỏi code nào: +> +> ```toml +> [[calls]] +> match = "when the user requests code examples, setup or configuration steps, or library/API documentation" +> tool = "context7" +> ``` +> +> Từ đó bạn sẽ nhận được tài liệu Context7 trong bất kỳ cuộc hội thoại liên quan nào mà không cần gõ thêm gì. Bạn có thể thêm các trường hợp sử dụng của mình vào phần match. + +### Sử dụng Library Id +> Nếu bạn đã biết chính xác thư viện nào muốn sử dụng, hãy thêm Context7 ID của nó vào prompt của bạn. Cách đó, Context7 MCP server có thể bỏ qua bước matching thư viện và trực tiếp tiếp tục với việc lấy tài liệu. +> +> ```txt +> implement basic authentication with supabase. use library /supabase/supabase for api and docs +> ``` +> +> Cú pháp dấu gạch chéo nói với MCP tool chính xác thư viện nào cần load tài liệu. + +## 💻 Phát Triển +Clone dự án và cài đặt dependencies: +```bash +pnpm i +``` +Build: +```bash +pnpm run build +``` +Chạy server: +```bash +node packages/mcp/dist/index.js +``` + +### Tham Số CLI +`context7-mcp` chấp nhận các CLI flags sau: +- `--transport ` – Transport để sử dụng (`stdio` theo mặc định). +- `--port ` – Port để lắng nghe khi sử dụng transport `http` (mặc định `3000`). +Ví dụ với http transport và port 8080: +```bash +node packages/mcp/dist/index.js --transport http --port 8080 +``` +
+Ví dụ Cấu hình Local + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"] + } + } +} +``` +
+ +
+Test với MCP Inspector + +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp +``` +
+ +## 🚨 Khắc Phục Sự Cố +
+Lỗi Module Not Found + +Nếu bạn gặp `ERR_MODULE_NOT_FOUND`, thử sử dụng `bunx` thay vì `npx`: +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` +Điều này thường giải quyết các vấn đề phân giải module trong môi trường mà `npx` không cài đặt hoặc phân giải packages đúng cách. +
+ +
+Vấn đề ESM Resolution + +Đối với lỗi như `Error: Cannot find module 'uriTemplate.js'`, thử flag `--experimental-vm-modules`: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` +
+ +
+Vấn đề TLS/Certificate + +Sử dụng flag `--experimental-fetch` để vượt qua các vấn đề liên quan đến TLS: +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"] + } + } +} +``` +
+ +
+Lỗi MCP Client Chung + +1. Thử thêm `@latest` vào tên package +2. Sử dụng `bunx` như một thay thế cho `npx` +3. Cân nhắc sử dụng `deno` như một thay thế khác +4. Đảm bảo bạn đang sử dụng Node.js v18 trở lên để hỗ trợ native fetch +
+ +## ⚠️ Tuyên Bố Miễn Trừ Trách Nhiệm +Các dự án Context7 được đóng góp bởi cộng đồng và mặc dù chúng tôi cố gắng duy trì chất lượng cao, chúng tôi không thể đảm bảo tính chính xác, đầy đủ hoặc bảo mật của tất cả tài liệu thư viện. Các dự án được liệt kê trong Context7 được phát triển và duy trì bởi các chủ sở hữu tương ứng của họ, không phải bởi Context7. Nếu bạn gặp bất kỳ nội dung đáng ngờ, không phù hợp hoặc có khả năng gây hại nào, vui lòng sử dụng nút "Report" trên trang dự án để thông báo cho chúng tôi ngay lập tức. Chúng tôi xem xét tất cả các báo cáo một cách nghiêm túc và sẽ xem xét nội dung được gắn cờ kịp thời để duy trì tính toàn vẹn và an toàn của nền tảng. Bằng cách sử dụng Context7, bạn thừa nhận rằng bạn làm như vậy theo quyết định và rủi ro của riêng mình. + +## 🤝 Kết Nối Với Chúng Tôi +Cập nhật và tham gia cộng đồng của chúng tôi: +- 📢 Theo dõi chúng tôi trên [X](https://x.com/context7ai) để có tin tức và cập nhật mới nhất +- 🌐 Truy cập [Website](https://context7.com) của chúng tôi +- 💬 Tham gia [Discord Community](https://upstash.com/discord) của chúng tôi + +## 📺 Context7 Trên Truyền Thông +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ Lịch Sử Star +[![Star History Chart](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 Giấy Phép +MIT diff --git a/i18n/README.zh-CN.md b/i18n/README.zh-CN.md new file mode 100644 index 0000000..3694410 --- /dev/null +++ b/i18n/README.zh-CN.md @@ -0,0 +1,155 @@ +![Cover](https://github.com/upstash/context7/blob/master/public/cover.png?raw=true) + +[![安装 MCP 服务器](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) + +# Context7 平台 - 最新代码文档赋能每个提示词 + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [![NPM Version](https://img.shields.io/npm/v/%40upstash%2Fcontext7-mcp?color=red)](https://www.npmjs.com/package/@upstash/context7-mcp) [![MIT licensed](https://img.shields.io/npm/l/%40upstash%2Fcontext7-mcp)](../LICENSE) + +[![English](https://img.shields.io/badge/docs-English-purple)](../README.md) [![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./README.zh-TW.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentação em Português (Brasil)]()](./README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./README.ru.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./README.uk.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./README.ar.md) [![Tiếng Việt](https://img.shields.io/badge/docs-Tiếng%20Việt-red)](./README.vi.md) + +## ❌ 不使用Context7 + +大语言模型（LLM）依赖过时或通用的库信息。你会遇到： + +- ❌ 代码示例已过时，基于一年前的训练数据 +- ❌ 幻觉产生的API根本不存在 +- ❌ 针对旧版本包的通用回答 + +## ✅ 使用Context7 + +Context7直接从源头获取最新的、特定版本的文档和代码示例——并将它们直接放入你的提示词中。 + +```txt +创建一个Next.js中间件，检查cookies中的有效JWT， +并将未认证用户重定向到 `/login`。use context7 +``` + +```txt +配置Cloudflare Worker脚本，将JSON API响应 +缓存五分钟。use context7 +``` + +```txt +查看Supabase的邮箱/密码注册Auth API。 +``` + +Context7将最新的代码示例和文档直接获取到你的LLM上下文中。无需切换标签页，不会因幻觉产生不存在的API，不会生成过时的代码。 + +支持两种模式： + +- **CLI + Skills** — 安装一个skill，引导你的代理使用 `ctx7` CLI命令获取文档（无需MCP） +- **MCP** — 注册一个Context7 MCP服务器，使你的代理能够原生调用文档工具 + +## 安装 + +> [!NOTE] +> **推荐使用API密钥**：在 [context7.com/dashboard](https://context7.com/dashboard) 获取免费API密钥，使用密钥后速率限制更高。 + +只需一条命令，即可为你的编码代理配置Context7： + +```bash +npx ctx7 setup +``` + +通过OAuth认证，生成API密钥，并安装相应的skill。你可以选择CLI+Skills模式或MCP模式。使用 `--cursor`、`--claude` 或 `--opencode` 指定目标代理。 + +如需稍后移除生成的配置，运行 `npx ctx7 remove`。如果通过 `npm install -g ctx7` 全局安装了CLI，需单独运行 `npm uninstall -g ctx7` 卸载该包。 + +如需手动配置，请将Context7服务器URL `https://mcp.context7.com/mcp` 添加到你的MCP客户端，并通过 `CONTEXT7_API_KEY` 请求头传递API密钥。详见下方链接的各客户端配置说明。 + +**[手动安装 / 其他客户端 →](https://context7.com/docs/resources/all-clients)** + +## 重点技巧 + +### 使用库 ID + +如果你已经确切知道要使用哪个库，请将其Context7 ID添加到你的提示词中。这样，Context7可以跳过库匹配步骤，直接检索文档。 + +```txt +使用Supabase实现基本身份验证。用/supabase/supabase作为库ID获取API和文档。 +``` + +斜杠语法明确告知Context7需加载文档的库。 + +### 指定版本 + +要获取特定库版本的文档，只需在提示词中提及版本： + +```txt +如何设置Next.js 14中间件？use context7 +``` + +Context7 将自动匹配适当的版本。 + +### 添加规则 + +如果通过 `ctx7 setup` 安装，skill会自动配置，触发Context7响应库相关问题。如需手动添加规则，请在你的编码代理中配置： + +- **Cursor**：`Cursor Settings > Rules` +- **Claude Code**：`CLAUDE.md` +- 或你的编码代理中的等效设置 + +**规则示例：** + +```txt +无需我明确要求，当我需要库或API文档、生成代码、设置或配置步骤时，始终使用Context7。 +``` + +## 可用工具 + +### CLI命令 + +- `ctx7 library `：按库名在Context7索引中搜索，返回匹配的库及其ID。 +- `ctx7 docs `：使用Context7兼容的库ID获取库文档（例如 `/mongodb/docs`、`/vercel/next.js`）。 + +### MCP工具 + +- `resolve-library-id`：将通用库名称解析为Context7兼容的库ID。 + - `query`（必需）：用户的问题或任务（用于按相关性排名结果） + - `libraryName`（必需）：要搜索的库名称 +- `query-docs`：使用Context7兼容的库ID获取库的文档。 + - `libraryId`（必需）：精确的Context7兼容的库ID（例如 `/mongodb/docs`、`/vercel/next.js`） + - `query`（必需）：用于获取相关文档的问题或任务 + +## 更多文档 + +- [CLI参考](https://context7.com/docs/clients/cli) - 完整CLI文档 +- [MCP客户端](https://context7.com/docs/resources/all-clients) - 30+客户端的手动MCP安装说明 +- [添加库](https://context7.com/docs/adding-libraries) - 将你的库提交到Context7 +- [故障排除](https://context7.com/docs/resources/troubleshooting) - 常见问题和解决方案 +- [API参考](https://context7.com/docs/api-guide) - REST API文档 +- [开发者指南](https://context7.com/docs/resources/developer) - 本地运行Context7 MCP + +## 免责声明 + +1- Context7项目由社区贡献，虽然我们努力保持高质量，但我们不能保证所有库文档的准确性、完整性或安全性。Context7中列出的项目由其各自所有者开发和维护，而非由Context7开发和维护。如果你遇到任何可疑、不当或潜在有害的内容，请使用项目页面上的“Report”按钮立即通知我们。我们认真对待所有举报，并将及时审查被举报的内容，以维护我们平台的完整性和安全性。使用Context7即表示你承认自行承担风险。 + +2- 本仓库托管MCP服务器的源代码。支持组件——API 后端、解析引擎和爬取引擎——是私有的，不包含在本仓库中。 + +## 🤝 与我们联系 + +保持更新并加入我们的社区： + +- 📢 在[X](https://x.com/context7ai)上关注我们获取最新新闻和更新 +- 🌐 访问我们的[网站](https://context7.com) +- 💬 加入我们的[Discord社区](https://upstash.com/discord) + +## 📺 Context7媒体报道 + +- [Better Stack："免费工具让Cursor智能10倍"](https://youtu.be/52FC3qObp9E) +- [Cole Medin："这绝对是AI编码助手的最佳MCP服务器"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers："Context7 + SequentialThinking MCP：这是AGI吗？"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO："Context7：新的MCP AI代理更新"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu："Context 7 MCP：即时获取文档 + VS Code配置方法"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers："Context7：将改变AI编码的新MCP服务器"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing："Context7 + Cline & RooCode：这个MCP服务器让CLINE效果提升100倍！"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel："5个让编码更爽的MCP服务器（即插即用）"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ Star 历史 + +[![Star历史图表](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 许可证 + +MIT diff --git a/i18n/README.zh-TW.md b/i18n/README.zh-TW.md new file mode 100644 index 0000000..dd20fec --- /dev/null +++ b/i18n/README.zh-TW.md @@ -0,0 +1,245 @@ +![Cover](https://github.com/upstash/context7/blob/master/public/cover.png?raw=true) + +[![安裝 MCP 伺服器](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) + +# Context7 MCP - 即時更新的程式碼文件，適用於任何提示 + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [![NPM Version](https://img.shields.io/npm/v/%40upstash%2Fcontext7-mcp?color=red)](https://www.npmjs.com/package/@upstash/context7-mcp) [![MIT licensed](https://img.shields.io/npm/l/%40upstash%2Fcontext7-mcp)](./LICENSE) + +[![English](https://img.shields.io/badge/docs-English-purple)](../README.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](./README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./README.fr.md) [![Documentação em Português (Brasil)]()](./README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./README.ru.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./README.uk.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./README.ar.md) [![Tiếng Việt](https://img.shields.io/badge/docs-Tiếng%20Việt-red)](./README.vi.md) + +## ❌ 沒有 Context7 + +大型語言模型（LLM）依賴過時或通用的函式庫資訊。你會遇到： + +- ❌ 程式碼範例已過時，基於一年前的訓練資料 +- ❌ 產生根本不存在的幻覺 API +- ❌ 針對舊版本套件的通用回答 + +## ✅ 有了 Context7 + +Context7 MCP 直接從來源取得最新的、特定版本的文件與程式碼範例——並直接放入你的提示中。 + +在你的提示中加入 `use context7`（或[設定規則](#新增規則)自動調用）： + +```txt +建立一個 Next.js 中介軟體，檢查 cookies 中的有效 JWT， +並將未認證使用者重新導向至 `/login`。use context7 +``` + +```txt +設定 Cloudflare Worker 腳本，將 JSON API 回應 +快取五分鐘。use context7 +``` + +Context7 將最新的程式碼範例與文件直接取得到你的 LLM 上下文中。不需切換分頁、不會產生不存在的幻覺 API、不會產生過時的程式碼。 + +## 安裝 + +> [!NOTE] +> **建議使用 API 金鑰**：在 [context7.com/dashboard](https://context7.com/dashboard) 取得免費 API 金鑰，可獲得更高的請求速率限制。 + +
+在 Cursor 中安裝 + +前往：`Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` + +建議將下列設定貼到你的 Cursor `~/.cursor/mcp.json` 檔案中。你也可以透過在專案資料夾中建立 `.cursor/mcp.json` 在特定專案中安裝。更多資訊請參閱 [Cursor MCP 文件](https://docs.cursor.com/context/model-context-protocol)。 + +> 自 Cursor 1.0 起，你可以點擊下方的安裝按鈕進行即時一鍵安裝。 + +#### Cursor 遠端伺服器連線 + +[![安裝 MCP 伺服器](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Cursor 本地伺服器連線 + +[![安裝 MCP 伺服器](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+在 Claude Code 中安裝 + +執行下列指令。更多資訊請參見 [Claude Code MCP 文件](https://code.claude.com/docs/en/mcp)。 + +#### Claude Code 本地伺服器連線 + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY +``` + +#### Claude Code 遠端伺服器連線 + +```sh +claude mcp add --scope user --header "CONTEXT7_API_KEY: YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp +``` + +
+ +
+在 Opencode 中安裝 + +將此內容加入你的 Opencode 設定檔。更多資訊請參見 [Opencode MCP 文件](https://opencode.ai/docs/mcp-servers)。 + +#### Opencode 遠端伺服器連線 + +```json +"mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "enabled": true + } +} +``` + +#### Opencode 本地伺服器連線 + +```json +{ + "mcp": { + "context7": { + "type": "local", + "command": ["npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "enabled": true + } + } +} +``` + +
+ +**[其他 IDE 和客戶端 →](https://context7.com/docs/resources/all-clients)** + +
+OAuth 認證 + +Context7 MCP 伺服器支援 OAuth 2.0 認證，適用於實作了 [MCP OAuth 規範](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)的 MCP 客戶端。 + +要使用 OAuth，請在客戶端設定中將端點從 `/mcp` 更改為 `/mcp/oauth`： + +```diff +- "url": "https://mcp.context7.com/mcp" ++ "url": "https://mcp.context7.com/mcp/oauth" +``` + +OAuth 僅適用於遠端 HTTP 連線。對於使用 stdio 傳輸的本地 MCP 連線，請改用 API 金鑰認證。 + +
+ +## 重要提示 + +### 新增規則 + +為避免每次都在提示中輸入 `use context7`，你可以在 MCP 客戶端中新增規則，自動為程式碼相關問題調用 Context7： + +- **Cursor**：`Cursor Settings > Rules` +- **Claude Code**：`CLAUDE.md` +- 或你的 MCP 客戶端中的等效設定 + +**規則範例：** + +```txt +當我需要函式庫/API 文件、程式碼產生、設定或設定步驟時，始終使用 Context7 MCP，無需我明確要求。 +``` + +### 使用函式庫 ID + +如果你已經確切知道要使用哪個函式庫，請將其 Context7 ID 加入你的提示中。這樣，Context7 MCP 伺服器可以跳過函式庫匹配步驟，直接取得文件。 + +```txt +使用 Supabase 實作基本身分驗證。use library /supabase/supabase 取得 API 和文件。 +``` + +斜線語法告訴 MCP 工具確切要為哪個函式庫載入文件。 + +### 指定版本 + +要取得特定函式庫版本的文件，只需在提示中提及版本： + +```txt +如何設定 Next.js 14 中介軟體？use context7 +``` + +Context7 將自動匹配適當的版本。 + +## 可用工具 + +Context7 MCP 提供下列 LLM 可使用的工具： + +- `resolve-library-id`：將通用函式庫名稱解析為 Context7 相容的函式庫 ID。 + - `query`（必填）：使用者的問題或任務（用於按相關性排名結果） + - `libraryName`（必填）：要搜尋的函式庫名稱 + +- `query-docs`：使用 Context7 相容的函式庫 ID 取得函式庫的文件。 + - `libraryId`（必填）：精確的 Context7 相容函式庫 ID（例如 `/mongodb/docs`、`/vercel/next.js`） + - `query`（必填）：用於取得相關文件的問題或任務 + +## 更多文件 + +- [更多 MCP 客戶端](https://context7.com/docs/resources/all-clients) - 30+ 客戶端的安裝說明 +- [新增函式庫](https://context7.com/docs/adding-libraries) - 將你的函式庫提交到 Context7 +- [疑難排解](https://context7.com/docs/resources/troubleshooting) - 常見問題與解決方案 +- [API 參考](https://context7.com/docs/api-guide) - REST API 文件 +- [開發者指南](https://context7.com/docs/resources/developer) - 本地執行 Context7 MCP + +## 免責聲明 + +1- Context7 專案由社群貢獻，雖然我們致力於維持高品質，但我們無法保證所有函式庫文件的準確性、完整性或安全性。Context7 中列出的專案由其各自擁有者開發和維護，而非由 Context7 開發和維護。如果你遇到任何可疑、不當或潛在有害的內容，請使用專案頁面上的「檢舉」按鈕立即通知我們。我們認真對待所有檢舉，並將及時審查標記的內容，以維護我們平台的完整性和安全性。使用 Context7 即表示你承認自行承擔風險。 + +2- 本儲存庫託管 MCP 伺服器的原始碼。支援元件——API 後端、解析引擎和爬取引擎——是私有的，不包含在本儲存庫中。 + +## 🤝 與我們聯繫 + +保持更新並加入我們的社群： + +- 📢 在 [X](https://x.com/context7ai) 上追蹤我們取得最新消息和更新 +- 🌐 造訪我們的[網站](https://context7.com) +- 💬 加入我們的 [Discord 社群](https://upstash.com/discord) + +## 📺 Context7 媒體報導 + +- [Better Stack：「免費工具讓 Cursor 智慧 10 倍」](https://youtu.be/52FC3qObp9E) +- [Cole Medin：「這絕對是 AI 程式助理最強 MCP 伺服器」](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers：「Context7 + SequentialThinking MCPs：這是 AGI 嗎？」](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO：「Context7：全新 MCP AI 代理更新」](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu：「Context 7 MCP：即時取得文件 + VS Code 設定」](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers：「Context7：將改變 AI 程式開發的新 MCP 伺服器」](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing：「Context7 + Cline & RooCode：這個 MCP 伺服器讓 CLINE 效率提升 100 倍！」](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel：「5 個讓程式開發如虎添翼的 MCP 伺服器（即插即用）」](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ Star 歷史 + +[![Star 歷史圖表](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 授權 + +MIT diff --git a/package.json b/package.json new file mode 100644 index 0000000..9781189 --- /dev/null +++ b/package.json @@ -0,0 +1,61 @@ +{ + "name": "@upstash/context7", + "private": true, + "version": "1.0.0", + "description": "Context7 monorepo - Documentation tools and SDKs", + "workspaces": [ + "packages/*" + ], + "scripts": { + "build": "pnpm -r run build", + "build:sdk": "pnpm --filter @upstash/context7-sdk build", + "build:mcp": "pnpm --filter @upstash/context7-mcp build", + "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build", + "typecheck": "pnpm -r run typecheck", + "test": "pnpm -r run test", + "test:sdk": "pnpm --filter @upstash/context7-sdk test", + "test:tools-ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk test", + "clean": "pnpm -r run clean && rm -rf node_modules", + "lint": "pnpm -r run lint", + "lint:check": "pnpm -r run lint:check", + "format": "pnpm -r run format", + "format:check": "pnpm -r run format:check", + "release": "pnpm build && changeset publish", + "release:snapshot": "changeset version --snapshot canary && pnpm build && changeset publish --tag canary --no-git-tag" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/upstash/context7.git" + }, + "keywords": [ + "modelcontextprotocol", + "mcp", + "context7", + "vibe-coding", + "developer tools", + "documentation", + "context" + ], + "author": "abdush", + "license": "MIT", + "bugs": { + "url": "https://github.com/upstash/context7/issues" + }, + "homepage": "https://github.com/upstash/context7#readme", + "devDependencies": { + "@changesets/cli": "^2.29.8", + "@types/node": "^25.0.3", + "@typescript-eslint/eslint-plugin": "^8.28.0", + "@typescript-eslint/parser": "^8.28.0", + "eslint": "^9.34.0", + "eslint-config-prettier": "^10.1.1", + "eslint-plugin-prettier": "^5.5.6", + "prettier": "^3.6.2", + "typescript": "^5.8.2", + "typescript-eslint": "^8.28.0" + }, + "dependencies": { + "@inquirer/core": "^11.1.1", + "@inquirer/type": "^4.0.3" + } +} diff --git a/packages/cli/.gitignore b/packages/cli/.gitignore new file mode 100644 index 0000000..deed335 --- /dev/null +++ b/packages/cli/.gitignore @@ -0,0 +1,3 @@ +node_modules/ +dist/ +.env diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md new file mode 100644 index 0000000..45fbe3a --- /dev/null +++ b/packages/cli/CHANGELOG.md @@ -0,0 +1,270 @@ +# Changelog + +## 0.5.4 + +### Patch Changes + +- 33229cb: Clarify the `query-docs` query description so it asks for a single concept per query. When a question spans multiple distinct topics, callers are now told to make a separate query per concept instead of combining them (unless the question is about how the concepts interact), which avoids diluted, shallow results. Applied consistently across the MCP server, CLI, pi, and AI SDK tools. + +## 0.5.3 + +### Patch Changes + +- acd0d46: Surface GitHub API error details when skill download fails (#2363) + + Previously, any GitHub API failure during `ctx7 setup` or `ctx7 setup --cli` produced the opaque message "GitHub API error", making it impossible to distinguish a 403 rate-limit from a 401 bad token or a 404 wrong branch. + + Changes: + - `fetchRepoTree` and `fetchDefaultBranch` now extract the HTTP status and GitHub error body, returning descriptive strings like `"HTTP 403: API rate limit exceeded"` + - `listSkillsFromGitHub` distinguishes a true 404 (repo not found) from other errors (rate-limit, bad credentials) that previously all collapsed into the same silent result + - When a request fails unauthenticated with a 403/429, a hint is shown: `run \`gh auth login\` or set the GITHUB_TOKEN env var to increase rate limits` + - Failed skill entries in the setup results table now show a red `✖` with the error detail on its own line instead of embedding it in the status string + +## 0.5.2 + +### Patch Changes + +- cb6aee1: Bump runtime dependencies: `commander` 13 -> 15 and `ora` 9.0 -> 9.4. +- 428af3e: Recover Context7 library IDs that Git Bash mangles on Windows. Git Bash rewrites a leading-slash argument like `/facebook/react` into a Windows path under the Git install dir (`C:/Program Files/Git/facebook/react`), causing `ctx7 docs` to reject it as invalid; this mainly affected users running ctx7 through Claude Code. The CLI now detects and undoes the conversion before validation, accepts the `//owner/repo` escape, and points users at that workaround for install layouts it can't auto-detect. +- c03bc9c: Store CLI files in XDG Base Directory locations instead of `~/.context7`. Credentials move to `$XDG_CONFIG_HOME/context7` (default `~/.config/context7`), updater state to `$XDG_STATE_HOME/context7` (default `~/.local/state/context7`), and `generate` previews to `$XDG_CACHE_HOME/context7` (default `~/.cache/context7`). Existing files in `~/.context7` are migrated automatically on first use; migration is best-effort and falls back to reading the legacy file if it cannot complete. The credentials file is always re-asserted to `0o600` after migration or write so it is never group/world-readable. Relative or empty `XDG_*` values are ignored per the spec. + +## 0.5.1 + +### Patch Changes + +- ea91d7d: `ctx7 login` now always uses the device-code flow. The localhost-callback path is removed — every install (laptop, SSH, Codespace, Docker, CI) goes through the same boxed prompt and verification page. Drops the `--device` flag (it was the opt-in for what's now the default). Older CLI versions (≤ 0.5.0) continue to work against the unchanged auth endpoints, so pinned installs are unaffected. + +## 0.5.0 + +### Minor Changes + +- 5a180d5: Add OAuth 2.0 device authorization flow (RFC 8628) for `ctx7 login` and `ctx7 setup`. Required for headless / remote hosts (SSH, Codespaces, Docker, CI) where the existing localhost-callback flow can't work — the browser was opening on the user's laptop while the callback listener ran on the remote host. + + The new flow prints a verification URL and short code, then polls a token endpoint. The user visits the URL on any device, signs in, and approves; the CLI receives the same `ctx7sk-…` API key it would have gotten from the legacy flow. Device flow is selected automatically when `SSH_CONNECTION` is set or `$DISPLAY` is missing on Linux, and can be forced with `ctx7 login --device`. Polling tolerates transient network errors and 5xx responses without ending the session. + +## 0.4.5 + +### Patch Changes + +- 2affada: `ctx7 setup` now properly supports `--antigravity`, installing skills to `.agent/skills`, a `GEMINI.md` rule section (Antigravity reads Gemini-family config), and MCP config to Antigravity 2.0's documented global path `~/.gemini/config/mcp_config.json` (with `httpUrl` for HTTP, matching the Gemini convention). Antigravity has no documented project-level MCP file, so `setup --antigravity --project --mcp` writes to the global location. Also removes the `--universal` flag from `setup`, which was advertised but silently ignored — it never propagated through agent selection, so passing it (e.g. `setup --cli --universal --project`) caused setup to fall back to auto-detection and write to the wrong directory. +- 268f52f: `ctx7 setup --api-key ` (without `--cli`, `--mcp`, or `-y`) now prompts to choose between MCP server and CLI + Skills modes. Previously, passing `--api-key` short-circuited to MCP, locking users out of the CLI + Skills option even though that mode also accepts an API key. Explicit `--mcp` / `--cli` / `--stdio` / `--oauth` / `-y` still skip the prompt as before. +- 2e97dae: Add deprecation warning to skill commands + +## 0.4.4 + +### Patch Changes + +- 7cacc94: Add `--json` flag to `ctx7 skills list` for machine-parseable output. Emits `{ skills: [{ name, path, source }] }` where `path` is absolute and `source` is the agent type (`universal`, `claude`, `cursor`, `antigravity`). Matches the existing `--json` pattern on `ctx7 library` and `ctx7 docs`. + +## 0.4.3 + +### Patch Changes + +- dea0e43: Declare `@inquirer/core` as a direct dependency of the CLI. It was previously imported in `selectOrInput.ts` but only resolvable as a transitive of `@inquirer/prompts`, which caused `ctx7` to fail at startup with `ERR_MODULE_NOT_FOUND` under pnpm's isolated node linker. +- 34fda7d: Add `--stdio` flag to `ctx7 setup` to configure Context7 as a local stdio MCP server. +- 61de754: Harden skill name handling during `ctx7 skills install` and `ctx7 skills remove`. Skill names from remote `SKILL.md` files are now restricted to a safe character set, and the install sinks assert the target directory is a direct child of the skills root before writing. + +## 0.4.2 + +### Patch Changes + +- 6c71e4d: Handle malformed MCP config files gracefully during `ctx7 remove` agent detection. Previously, an unparseable JSON config at any agent's well-known path (e.g. a hand-edited `~/.claude.json`) would crash the command with an unhandled `SyntaxError` before it could do anything. The detector now skips the offending file and logs a warning naming the path and parse error so the user can fix it, while detection continues for the remaining agents. +- 4056850: Respect `CLAUDE_CONFIG_DIR` env var when resolving Claude Code's global config, rules, skills, and detection paths + +## 0.4.1 + +### Patch Changes + +- 1aa3430: Remove research mode entirely from the MCP server and CLI. 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`. + +## 0.4.0 + +### Minor Changes + +- 17b864f: Expose research mode through the MCP `researchMode` tool and the CLI `docs --research` flag for deep, agent-driven documentation answers. + +### Patch Changes + +- 4feee15: Add CLI update notifications and a new `ctx7 upgrade` command. The CLI now checks for newer versions with cached state, shows a non-blocking notice before interactive commands, and provides safer upgrade guidance across npm, pnpm, bun, and ephemeral runner setups. +- f056b14: Add `ctx7 remove` as the cleanup counterpart to `ctx7 setup`, with safer detection and removal behavior. The command now prompts only for agents with actual Context7 artifacts, preserves non-Context7 MCP configuration when removing entries, and includes stronger test coverage for JSON and TOML cleanup. + +## 0.3.13 + +### Patch Changes + +- 3f6e310: Fix skill installation path validation on Windows so valid files inside the target directory are not rejected due to backslash-separated resolved paths. + +## 0.3.12 + +### Patch Changes + +- 33f2338: Add Codex-specific CLI setup guidance so generated rules and the installed `find-docs` skill tell Codex to rerun Context7 CLI requests outside the default sandbox after DNS or network failures. + +## 0.3.11 + +### Patch Changes + +- bc8eaf1: Add `--all-agents` and `--yes` support to `ctx7 skills install` for non-interactive multi-agent installs. + +## 0.3.10 + +### Patch Changes + +- fb29170: Add Gemini CLI support to setup command +- 89d4862: Use GITHUB_TOKEN/GH_TOKEN or gh CLI auth for skill downloads to avoid GitHub API rate limits and support private repos +- 8322879: Improve resolve libryar id tool prompt to provide the libraryName query with proper format + +## 0.3.9 + +### Patch Changes + +- 6961bdd: Allow re-selecting already configured agents in ctx7 setup and overwrite existing MCP config entries instead of skipping them. Fix TOML replacement to correctly handle sub-sections and prevent whitespace drift on repeated runs. + +## 0.3.8 + +### Patch Changes + +- a667712: Update search filter warning +- d739f9b: Fix OpenCode MCP setup to resolve all config file variants (opencode.json, opencode.jsonc, .opencode.json, .opencode.jsonc) +- 4f13168: Install rules alongside skills in `ctx7 setup` for better trigger rates + - CLI setup now installs a rule file for each agent (previously only installed the skill) + - Rule content fetched from GitHub, with agent-specific formatting (alwaysApply for Cursor) + - Updated find-docs skill description for higher invocation rates (66% -> 98%) + - Added Codex agent support with AGENTS.md append + - OpenCode now writes to AGENTS.md instead of .opencode/rules/ + - Selective rule content with explicit when-to-use/when-not-to-use guidance + +- c3c2647: Use ~/.agents/skills instead of ~/.config/agents/skills for global universal skill installs + +## 0.3.7 + +### Patch Changes + +- 93eaf54: Remove shell:true from spawn call in generate command to prevent command injection via EDITOR env variable +- 8c5cf7d: Prevent directory traversal in skill file installation by validating resolved paths stay within the target directory + +## 0.3.6 + +### Patch Changes + +- fae6127: Add active teamspace name to whoami command output +- 4b63117: Reorder setup mode choices to show MCP server first +- 18b3292: Add token refresh support, centralize auth constants, switch whoami to internal API endpoint with teamspace display, and add unit tests for CLI auth utilities and commands + +## 0.3.5 + +### Patch Changes + +- 7e60d05: - feat(cli): track install count events when skills are installed via `ctx7 setup` + +## 0.3.4 + +### Patch Changes + +- 62dc278: - feat(cli): enumerate popularity with a 4-star scale in skill search, install, and suggest results + - feat(cli): show install count range and trust score in skill hover details + - fix(cli): rename "docs" skill to "find-docs" in setup output and prompts +- 04130b5: Consolidate skills under /skills with canonical sources: rename docs→find-docs, ctx7-cli→context7-cli, add context7-mcp as canonical MCP skill. MCP setup now downloads skill from GitHub instead of using hardcoded content. +- d418405: Add CLI mode to ctx7 setup for installing the docs skill without MCP configuration + +## 0.3.3 + +### Patch Changes + +- 31b4fb8: Align CLI library output format with MCP: use labeled fields (Title, Context7-compatible library ID, Description, Code Snippets, Source Reputation, Benchmark Score, Versions) and categorical reputation labels (High/Medium/Low/Unknown) instead of numeric trust scores +- 9de3f06: Display warning when public library access filter is being used to filter libraries. +- 05a4406: Remove default selection of Universal agent target during skills install prompt +- 9aae852: Show source repository next to skill name in search and suggest results for easier disambiguation + +## 0.3.2 + +### Patch Changes + +- df60e3e: Add `library` and `docs` commands for querying library documentation from the terminal + +## 0.3.1 + +### Patch Changes + +- c66950a: Install documentation-lookup skill during `ctx7 setup` + +## 0.3.0 + +### Minor Changes + +- 3d66191: Add `ctx7 setup` command for configuring Context7 MCP and rules across Claude Code, Cursor, and OpenCode + +## 0.2.4 + +### Patch Changes + +- 4663c15: - Adopt `.agents/skills` as universal install target, supporting multiple agents with a single installation + - Replace `--codex`, `--opencode`, and `--amp` flags with single `--universal` flag + - Improve checkbox UI with aligned column headers for better readability + +## 0.2.3 + +### Patch Changes + +- 0981656: Add `skills suggest` command that scans your project's dependencies (package.json, requirements.txt, pyproject.toml) and recommends relevant skills. Results show install counts, trust scores, and which dependency each skill matches. + +## 0.2.2 + +### Patch Changes + +- 6328ed1: Skill search & generate command improvements: + - Add "Installs" and "Trust(0-10)" columns to skill search results with aligned column headers + - Auto-login via OAuth when the generate command requires authentication instead of showing an error + - Reorder question options so the recommended choice always appears first with a "✓ Recommended" badge + - Add "View skill" action that opens generated content in the user's default editor (`$EDITOR`) + - Revamp generate wizard copy: do/don't examples for skill descriptions, rename "libraries" to "sources", and clarify follow-up question and generation spinner text + +## 0.2.1 + +### Patch Changes + +- 2f7cc42: Show exact install counts instead of rounded values, sort skills by install count in the install command, and display "installs" column header inline with the prompt +- 85b905e: Add CLI telemetry for usage metrics collection (commands, searches, installs, generation feedback) via fire-and-forget events to /api/v2/cli/events. Respects CTX7_TELEMETRY_DISABLED env var. + +## 0.2.0 + +### Minor Changes + +- 8ba484c: Add AI-powered skill generation with `skills generate` command, including library search, clarifying questions, real-time query progress, feedback loop, and weekly quota management. +- aacfd31: Add OAuth 2.0 authentication with login, logout, and whoami commands. + +### Patch Changes + +- 572c3ca: Simplify `skills list` command to show all detected IDE skill directories without prompts. + +## 0.1.5 + +### Improvements + +- Improved skill selection UX with metadata panel showing Skill, Repo, and Description +- Clickable links in metadata (Skill → context7.com, Repo → GitHub) +- Display install counts next to skill names (e.g., `↓100+`, `↓50+`) +- Numbered list items for easier reference +- Select hovered item on Enter without needing to Space-select first +- Green highlight for hovered row +- Fix circular scrolling - navigation now stops at list boundaries + +## 0.1.4 + +- Add prompt injection detection with warning messages for blocked skills + +## 0.1.3 + +- Auto-detect installed IDE configurations in project/global directories +- Add confirmation prompt before installing to detected locations + +## 0.1.0 + +- Initial stable release +- Commands: `install`, `search`, `list`, `remove`, `info` +- Multi-IDE support: Claude, Cursor, Codex, OpenCode, Amp, Antigravity +- Global and project-level skill installation +- Symlink support (Claude gets original files, others get symlinks) +- Short aliases: `si`, `ss` +- Single skill installation via `ctx7 skills install /owner/repo skill-name` +- Installation tracking metrics diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 0000000..731da4f --- /dev/null +++ b/packages/cli/README.md @@ -0,0 +1,158 @@ +# ctx7 + +CLI for [Context7](https://context7.com) - query up-to-date library documentation and configure Context7 for AI coding agents. + +## Installation + +```bash +# Run directly with npx (no install needed) +npx ctx7 + +# Or install globally +npm install -g ctx7 +``` + +## Quick Start + +```bash +# Set up Context7 MCP for your coding agents +ctx7 setup + +# Remove Context7 setup later +ctx7 remove + +# Target a specific agent +ctx7 setup --cursor +ctx7 setup --claude +ctx7 setup --opencode +``` + +### Library Documentation + +```bash +# Find a library +ctx7 library react +ctx7 library nextjs "app router" + +# Get documentation +ctx7 docs /facebook/react "useEffect cleanup" +ctx7 docs /vercel/next.js "middleware" +``` + +## Usage + +### Find a library + +Resolve a library name to a Context7 library ID. + +```bash +ctx7 library react +ctx7 library nextjs "app router setup" +ctx7 library prisma "database relations" + +# Output as JSON +ctx7 library react --json +``` + +### Query documentation + +Fetch documentation for a specific library using its Context7 ID. + +```bash +ctx7 docs /facebook/react "useEffect cleanup" +ctx7 docs /vercel/next.js "middleware authentication" +ctx7 docs /prisma/prisma "one-to-many relations" + +# Output as JSON +ctx7 docs /facebook/react "hooks" --json +``` + +### Setup + +Configure Context7 MCP and a rule for your AI coding agents. Authenticates via OAuth, generates an API key, and writes the config. + +```bash +# Interactive (prompts for agent selection) +ctx7 setup + +# Target specific agents +ctx7 setup --cursor +ctx7 setup --claude +ctx7 setup --opencode + +# Use an existing API key instead of OAuth +ctx7 setup --api-key YOUR_API_KEY + +# Use OAuth endpoint (IDE handles auth flow) +ctx7 setup --oauth + +# Configure for current project only (default is global) +ctx7 setup --project + +# Skip prompts +ctx7 setup --yes +``` + +### Uninstall setup + +Remove the Context7 setup written by `ctx7 setup`. By default this removes both MCP setup and CLI setup for the selected agent. + +```bash +# Interactive +ctx7 remove + +# Target specific agents +ctx7 remove --cursor +ctx7 remove --claude --project + +# Remove both setup modes explicitly +ctx7 remove --cursor --all + +# Remove only one setup mode +ctx7 remove --cursor --cli +ctx7 remove --claude --mcp +``` + +If you installed the CLI itself globally with `npm install -g ctx7`, remove that separately with `npm uninstall -g ctx7`. If you use `npx ctx7`, there is no permanent CLI install to remove. + +### Authentication + +Log in to access authenticated setup and higher documentation rate limits. + +```bash +# Log in (opens browser for OAuth) +ctx7 login + +# Check login status +ctx7 whoami + +# Log out +ctx7 logout +``` + +## Supported Clients + +The CLI automatically detects which AI coding assistants you have installed and configures Context7 for them: + +| Client | Skills Directory | +| ------------------------------------------------------------------- | ----------------- | +| Universal (Amp, Codex, Gemini CLI, GitHub Copilot, OpenCode + more) | `.agents/skills/` | +| Claude Code | `.claude/skills/` | +| Cursor | `.cursor/skills/` | +| Antigravity | `.agent/skills/` | + +## Disabling Telemetry + +The CLI collects anonymous usage data to help improve the product. To disable telemetry, set the `CTX7_TELEMETRY_DISABLED` environment variable: + +```bash +# For a single command +CTX7_TELEMETRY_DISABLED=1 ctx7 docs /facebook/react "useEffect examples" + +# Or export in your shell profile (~/.bashrc, ~/.zshrc, etc.) +export CTX7_TELEMETRY_DISABLED=1 +``` + +## Learn More + +Visit [context7.com](https://context7.com) for documentation lookup and setup guides. diff --git a/packages/cli/eslint.config.js b/packages/cli/eslint.config.js new file mode 100644 index 0000000..f91d98c --- /dev/null +++ b/packages/cli/eslint.config.js @@ -0,0 +1,47 @@ +import { defineConfig } from "eslint/config"; +import tseslint from "typescript-eslint"; +import eslintPluginPrettier from "eslint-plugin-prettier"; + +export default defineConfig( + { + // Base ESLint configuration + ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**", "tsup.config.ts", "vitest.config.ts"], + }, + { + files: ["**/*.ts", "**/*.tsx"], + languageOptions: { + ecmaVersion: 2020, + sourceType: "module", + parser: tseslint.parser, + parserOptions: { + project: "./tsconfig.json", + tsconfigRootDir: import.meta.dirname, + }, + globals: { + // Add Node.js globals + process: "readonly", + require: "readonly", + module: "writable", + console: "readonly", + }, + }, + // Settings for all files + linterOptions: { + reportUnusedDisableDirectives: true, + }, + plugins: { + "@typescript-eslint": tseslint.plugin, + prettier: eslintPluginPrettier, + }, + rules: { + // TypeScript recommended rules + ...tseslint.configs.recommended.rules, + // TypeScript rules + "@typescript-eslint/explicit-module-boundary-types": "off", + "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }], + "@typescript-eslint/no-explicit-any": "warn", + // Prettier integration + "prettier/prettier": "error", + }, + } +); diff --git a/packages/cli/package.json b/packages/cli/package.json new file mode 100644 index 0000000..232f952 --- /dev/null +++ b/packages/cli/package.json @@ -0,0 +1,69 @@ +{ + "name": "ctx7", + "version": "0.5.4", + "description": "Context7 CLI - Fetch documentation context and configure Context7", + "type": "module", + "bin": { + "ctx7": "./dist/index.js" + }, + "files": [ + "dist" + ], + "scripts": { + "build": "tsup", + "dev": "tsup --watch", + "typecheck": "tsc --noEmit", + "lint": "eslint src --fix", + "lint:check": "eslint src", + "format": "prettier --write src", + "format:check": "prettier --check src", + "clean": "rm -rf dist node_modules", + "test": "vitest run", + "test:watch": "vitest" + }, + "dependencies": { + "@inquirer/core": "^11.1.1", + "@inquirer/prompts": "^8.2.0", + "boxen": "^8.0.1", + "commander": "^15.0.0", + "figlet": "^1.9.4", + "open": "^10.1.0", + "ora": "^9.4.0", + "picocolors": "^1.1.1" + }, + "devDependencies": { + "@types/figlet": "^1.7.0", + "@types/node": "^22.19.1", + "@typescript-eslint/eslint-plugin": "^8.28.0", + "@typescript-eslint/parser": "^8.28.0", + "eslint": "^9.34.0", + "eslint-plugin-prettier": "^5.5.6", + "prettier": "^3.6.2", + "tsup": "^8.5.0", + "typescript": "^5.8.2", + "typescript-eslint": "^8.28.0", + "vitest": "^4.1.9" + }, + "keywords": [ + "context7", + "cli", + "ai", + "skills", + "documentation", + "mcp" + ], + "author": "Upstash", + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/upstash/context7.git", + "directory": "packages/cli" + }, + "bugs": { + "url": "https://github.com/upstash/context7/issues" + }, + "homepage": "https://context7.com", + "engines": { + "node": ">=18" + } +} diff --git a/packages/cli/src/__tests__/auth-commands.test.ts b/packages/cli/src/__tests__/auth-commands.test.ts new file mode 100644 index 0000000..9c7e81b --- /dev/null +++ b/packages/cli/src/__tests__/auth-commands.test.ts @@ -0,0 +1,320 @@ +import { describe, test, expect, vi, beforeEach, afterEach } from "vitest"; +import { Command } from "commander"; + +const mockGetValidAccessToken = vi.fn(); +const mockClearTokens = vi.fn(); +const mockSaveTokens = vi.fn(); +const mockStartDeviceAuthorization = vi.fn(); +const mockPollDeviceToken = vi.fn(); + +vi.mock("../utils/auth.js", () => ({ + getValidAccessToken: (...args: unknown[]) => mockGetValidAccessToken(...args), + clearTokens: (...args: unknown[]) => mockClearTokens(...args), + saveTokens: (...args: unknown[]) => mockSaveTokens(...args), + startDeviceAuthorization: (...args: unknown[]) => mockStartDeviceAuthorization(...args), + pollDeviceToken: (...args: unknown[]) => mockPollDeviceToken(...args), + DEFAULT_DEVICE_POLL_INTERVAL_SECONDS: 5, +})); + +vi.mock("../utils/tracking.js", () => ({ + trackEvent: vi.fn(), +})); + +const mockSpinner = { + start: vi.fn().mockReturnThis(), + stop: vi.fn().mockReturnThis(), + succeed: vi.fn().mockReturnThis(), + fail: vi.fn().mockReturnThis(), + text: "", +}; +vi.mock("ora", () => ({ default: () => mockSpinner })); + +const mockOpen = vi.fn().mockResolvedValue(undefined); +vi.mock("open", () => ({ default: (...args: unknown[]) => mockOpen(...args) })); + +vi.mock("../constants.js", () => ({ CLI_CLIENT_ID: "test-client-id" })); +vi.mock("../utils/api.js", () => ({ getBaseUrl: () => "https://test.context7.com" })); + +import { registerAuthCommands, performLogin } from "../commands/auth.js"; +import { trackEvent } from "../utils/tracking.js"; + +let logOutput: string[]; +let errorOutput: string[]; +let originalExit: typeof process.exit; + +beforeEach(() => { + vi.clearAllMocks(); + logOutput = []; + errorOutput = []; + vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => { + logOutput.push(args.join(" ")); + }); + vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => { + errorOutput.push(args.join(" ")); + }); + originalExit = process.exit; + process.exit = vi.fn() as never; + + vi.stubGlobal( + "fetch", + vi.fn(() => { + throw new Error("fetch not mocked"); + }) + ); +}); + +afterEach(() => { + process.exit = originalExit; + vi.unstubAllGlobals(); + vi.restoreAllMocks(); +}); + +async function runCommand(...args: string[]): Promise { + const program = new Command(); + program.exitOverride(); // throw instead of process.exit on commander errors + registerAuthCommands(program); + await program.parseAsync(["node", "test", ...args]); +} + +describe("login command", () => { + test("skips login when valid token exists", async () => { + mockGetValidAccessToken.mockResolvedValue("existing-token"); + await runCommand("login"); + expect(logOutput.some((l) => l.includes("already logged in"))).toBe(true); + }); + + test("tracks login event", async () => { + mockGetValidAccessToken.mockResolvedValue("existing-token"); + await runCommand("login"); + expect(trackEvent).toHaveBeenCalledWith("command", { name: "login" }); + }); + + test("calls process.exit(1) when login fails", async () => { + mockGetValidAccessToken.mockResolvedValue(null); + mockClearTokens.mockReturnValue(false); + mockStartDeviceAuthorization.mockRejectedValue(new Error("network down")); + + await runCommand("login").catch(() => {}); + expect(process.exit).toHaveBeenCalledWith(1); + }); +}); + +describe("logout command", () => { + test("logs success when tokens were cleared", async () => { + mockClearTokens.mockReturnValue(true); + await runCommand("logout"); + expect(logOutput.some((l) => l.includes("Logged out successfully"))).toBe(true); + }); + + test("logs 'not logged in' when no tokens existed", async () => { + mockClearTokens.mockReturnValue(false); + await runCommand("logout"); + expect(logOutput.some((l) => l.includes("You are not logged in"))).toBe(true); + }); + + test("tracks logout event", async () => { + mockClearTokens.mockReturnValue(false); + await runCommand("logout"); + expect(trackEvent).toHaveBeenCalledWith("command", { name: "logout" }); + }); +}); + +describe("whoami command", () => { + test("shows 'Not logged in' when no valid token", async () => { + mockGetValidAccessToken.mockResolvedValue(null); + await runCommand("whoami"); + expect(logOutput.some((l) => l.includes("Not logged in"))).toBe(true); + }); + + test("fetches and displays user info when logged in", async () => { + mockGetValidAccessToken.mockResolvedValue("valid-token"); + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: true, + json: () => + Promise.resolve({ + success: true, + name: "Test User", + email: "test@example.com", + teamspace: null, + }), + }) + ); + + await runCommand("whoami"); + expect(logOutput.some((l) => l.includes("Logged in"))).toBe(true); + expect(logOutput.some((l) => l.includes("Test User"))).toBe(true); + expect(logOutput.some((l) => l.includes("test@example.com"))).toBe(true); + }); + + test("shows session expired hint when fetch fails", async () => { + mockGetValidAccessToken.mockResolvedValue("valid-token"); + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: false, + json: () => Promise.reject(new Error("fail")), + }) + ); + + await runCommand("whoami"); + expect(logOutput.some((l) => l.includes("Session may be expired"))).toBe(true); + }); + + test("tracks whoami event", async () => { + mockGetValidAccessToken.mockResolvedValue(null); + await runCommand("whoami"); + expect(trackEvent).toHaveBeenCalledWith("command", { name: "whoami" }); + }); +}); + +describe("performLogin", () => { + const authorization = { + device_code: "dc", + user_code: "ABCD-EFGH", + verification_uri: "https://t.example/oauth/device", + verification_uri_complete: "https://t.example/oauth/device?user_code=ABCD-EFGH", + expires_in: 600, + interval: 0, // 0ms poll cadence so tests don't need fake timers + }; + + beforeEach(() => { + // Quiet whoami so announceIdentity falls back without polluting stdout. + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ ok: false, json: () => Promise.resolve({}) }) + ); + }); + + test("returns access_token on approved", async () => { + mockStartDeviceAuthorization.mockResolvedValue(authorization); + mockPollDeviceToken.mockResolvedValue({ + status: "approved", + tokens: { access_token: "ctx7sk-x", token_type: "bearer" }, + }); + + const result = await performLogin(false); + expect(result).toBe("ctx7sk-x"); + expect(mockSaveTokens).toHaveBeenCalledWith({ + access_token: "ctx7sk-x", + token_type: "bearer", + }); + }); + + test("returns null on denied", async () => { + mockStartDeviceAuthorization.mockResolvedValue(authorization); + mockPollDeviceToken.mockResolvedValue({ status: "denied" }); + + expect(await performLogin(false)).toBeNull(); + expect(mockSaveTokens).not.toHaveBeenCalled(); + }); + + test("returns null on expired", async () => { + mockStartDeviceAuthorization.mockResolvedValue(authorization); + mockPollDeviceToken.mockResolvedValue({ status: "expired" }); + + expect(await performLogin(false)).toBeNull(); + expect(mockSaveTokens).not.toHaveBeenCalled(); + }); + + test("keeps polling on transient errors and applies backoff (RFC 8628 §3.5)", async () => { + vi.useFakeTimers(); + try { + mockStartDeviceAuthorization.mockResolvedValue(authorization); + mockPollDeviceToken + .mockResolvedValueOnce({ status: "transient", errorMessage: "ECONN" }) + .mockResolvedValueOnce({ status: "pending" }) + .mockResolvedValueOnce({ + status: "approved", + tokens: { access_token: "t", token_type: "bearer" }, + }); + + const pending = performLogin(false); + // transient bumps the interval by 5s (mirroring slow_down), so the + // 2nd and 3rd polls each need a 5s wait. Advance enough to cover both. + await vi.advanceTimersByTimeAsync(11_000); + const result = await pending; + expect(result).toBe("t"); + expect(mockPollDeviceToken).toHaveBeenCalledTimes(3); + } finally { + vi.useRealTimers(); + } + }); + + test("backs off polling cadence when slow_down is returned", async () => { + vi.useFakeTimers(); + try { + mockStartDeviceAuthorization.mockResolvedValue(authorization); + mockPollDeviceToken.mockResolvedValueOnce({ status: "slow_down" }).mockResolvedValueOnce({ + status: "approved", + tokens: { access_token: "t", token_type: "bearer" }, + }); + + const pending = performLogin(false); + // First poll fires after the initial 0ms interval; slow_down then + // bumps the interval by 5000ms before the second poll. + await vi.advanceTimersByTimeAsync(5500); + const result = await pending; + expect(result).toBe("t"); + expect(mockPollDeviceToken).toHaveBeenCalledTimes(2); + } finally { + vi.useRealTimers(); + } + }); + + test("returns null when start request throws", async () => { + mockStartDeviceAuthorization.mockRejectedValue(new Error("network down")); + + expect(await performLogin(false)).toBeNull(); + expect(mockPollDeviceToken).not.toHaveBeenCalled(); + }); + + test("opens verification_uri_complete when openBrowser=true and stdin is non-TTY", async () => { + const originalIsTTY = process.stdin.isTTY; + Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true }); + try { + mockStartDeviceAuthorization.mockResolvedValue(authorization); + mockPollDeviceToken.mockResolvedValue({ + status: "approved", + tokens: { access_token: "t", token_type: "bearer" }, + }); + + await performLogin(true); + expect(mockOpen).toHaveBeenCalledWith(authorization.verification_uri_complete); + } finally { + Object.defineProperty(process.stdin, "isTTY", { value: originalIsTTY, configurable: true }); + } + }); + + test("skips opening a browser when openBrowser=false", async () => { + mockStartDeviceAuthorization.mockResolvedValue(authorization); + mockPollDeviceToken.mockResolvedValue({ + status: "approved", + tokens: { access_token: "t", token_type: "bearer" }, + }); + + await performLogin(false); + expect(mockOpen).not.toHaveBeenCalled(); + }); + + test("defaults poll interval to 5s when server omits it (RFC 8628 §3.2)", async () => { + vi.useFakeTimers(); + try { + mockStartDeviceAuthorization.mockResolvedValue({ ...authorization, interval: undefined }); + mockPollDeviceToken.mockResolvedValueOnce({ status: "pending" }).mockResolvedValueOnce({ + status: "approved", + tokens: { access_token: "t", token_type: "bearer" }, + }); + + const pending = performLogin(false); + // Two 5s polls. + await vi.advanceTimersByTimeAsync(11_000); + const result = await pending; + expect(result).toBe("t"); + expect(mockPollDeviceToken).toHaveBeenCalledTimes(2); + } finally { + vi.useRealTimers(); + } + }); +}); diff --git a/packages/cli/src/__tests__/auth-utils.test.ts b/packages/cli/src/__tests__/auth-utils.test.ts new file mode 100644 index 0000000..6514084 --- /dev/null +++ b/packages/cli/src/__tests__/auth-utils.test.ts @@ -0,0 +1,430 @@ +import { describe, test, expect, vi, beforeEach, afterEach } from "vitest"; + +vi.mock("fs", () => { + const fns = { + existsSync: vi.fn(), + mkdirSync: vi.fn(), + writeFileSync: vi.fn(), + readFileSync: vi.fn(), + unlinkSync: vi.fn(), + renameSync: vi.fn(), + chmodSync: vi.fn(), + }; + return { ...fns, default: fns }; +}); + +vi.mock("../constants.js", () => ({ CLI_CLIENT_ID: "test-client-id" })); +vi.mock("../utils/api.js", () => ({ getBaseUrl: () => "https://test.context7.com" })); + +import * as fs from "fs"; +import { + saveTokens, + loadTokens, + clearTokens, + isTokenExpired, + getValidAccessToken, + startDeviceAuthorization, + pollDeviceToken, + type TokenData, +} from "../utils/auth.js"; + +const mfs = vi.mocked(fs); +const CREDENTIALS_PATH = "/fake-home/.config/context7/credentials.json"; +const LEGACY_CREDENTIALS_PATH = "/fake-home/.context7/credentials.json"; +const CONFIG_DIR_PATH = "/fake-home/.config/context7"; + +beforeEach(() => { + vi.clearAllMocks(); + // os.homedir() reads $HOME first on POSIX, so stubbing the env var pins the + // home directory deterministically without mocking the `os` builtin (which + // resolves unreliably across Node versions / worker pooling in CI). + vi.stubEnv("HOME", "/fake-home"); + vi.stubEnv("XDG_CONFIG_HOME", undefined); + vi.stubEnv("XDG_STATE_HOME", undefined); + vi.stubEnv("XDG_CACHE_HOME", undefined); + vi.stubGlobal( + "fetch", + vi.fn(() => { + throw new Error("fetch not mocked for this test"); + }) + ); +}); + +afterEach(() => { + vi.unstubAllGlobals(); + vi.unstubAllEnvs(); +}); + +describe("saveTokens", () => { + test("creates config directory if it does not exist", () => { + mfs.existsSync.mockReturnValue(false); + saveTokens({ access_token: "tok", token_type: "bearer" }); + expect(mfs.mkdirSync).toHaveBeenCalledWith(CONFIG_DIR_PATH, { recursive: true, mode: 0o700 }); + }); + + test("skips directory creation if it already exists", () => { + mfs.existsSync.mockReturnValue(true); + saveTokens({ access_token: "tok", token_type: "bearer" }); + expect(mfs.mkdirSync).not.toHaveBeenCalled(); + }); + + test("writes credentials file with 0o600 permissions", () => { + mfs.existsSync.mockReturnValue(true); + saveTokens({ access_token: "tok", token_type: "bearer" }); + expect(mfs.writeFileSync).toHaveBeenCalledWith(CREDENTIALS_PATH, expect.any(String), { + mode: 0o600, + }); + }); + + test("enforces 0o600 even when the credentials file already exists", () => { + // writeFileSync's mode is ignored for an existing file, so chmod must run. + mfs.existsSync.mockReturnValue(true); + saveTokens({ access_token: "tok", token_type: "bearer" }); + expect(mfs.chmodSync).toHaveBeenCalledWith(CREDENTIALS_PATH, 0o600); + }); + + test("honors XDG_CONFIG_HOME for credentials", () => { + vi.stubEnv("XDG_CONFIG_HOME", "/custom-config"); + mfs.existsSync.mockReturnValue(false); + saveTokens({ access_token: "tok", token_type: "bearer" }); + + expect(mfs.mkdirSync).toHaveBeenCalledWith("/custom-config/context7", { + recursive: true, + mode: 0o700, + }); + expect(mfs.writeFileSync).toHaveBeenCalledWith( + "/custom-config/context7/credentials.json", + expect.any(String), + { mode: 0o600 } + ); + }); + + test("computes expires_at from expires_in when expires_at is absent", () => { + mfs.existsSync.mockReturnValue(true); + const now = 1000000; + vi.spyOn(Date, "now").mockReturnValue(now); + saveTokens({ access_token: "tok", token_type: "bearer", expires_in: 3600 }); + const written = JSON.parse(mfs.writeFileSync.mock.calls[0][1] as string); + expect(written.expires_at).toBe(now + 3600 * 1000); + }); + + test("preserves existing expires_at if already set", () => { + mfs.existsSync.mockReturnValue(true); + saveTokens({ access_token: "tok", token_type: "bearer", expires_at: 999, expires_in: 3600 }); + const written = JSON.parse(mfs.writeFileSync.mock.calls[0][1] as string); + expect(written.expires_at).toBe(999); + }); +}); + +describe("loadTokens", () => { + test("returns null when credentials file does not exist", () => { + mfs.existsSync.mockReturnValue(false); + expect(loadTokens()).toBeNull(); + }); + + test("returns parsed TokenData when file exists", () => { + const tokens: TokenData = { access_token: "tok", token_type: "bearer" }; + mfs.existsSync.mockReturnValue(true); + mfs.readFileSync.mockReturnValue(JSON.stringify(tokens)); + expect(loadTokens()).toEqual(tokens); + }); + + test("migrates credentials from the legacy ~/.context7 path before reading", () => { + const tokens: TokenData = { access_token: "tok", token_type: "bearer" }; + let migrated = false; + mfs.existsSync.mockImplementation((filePath) => + filePath === CREDENTIALS_PATH + ? migrated + : filePath === LEGACY_CREDENTIALS_PATH || filePath === CONFIG_DIR_PATH + ); + mfs.renameSync.mockImplementation(() => { + migrated = true; + }); + mfs.readFileSync.mockReturnValue(JSON.stringify(tokens)); + + expect(loadTokens()).toEqual(tokens); + expect(mfs.renameSync).toHaveBeenCalledWith(LEGACY_CREDENTIALS_PATH, CREDENTIALS_PATH); + // rename preserves the legacy mode, so migration must re-assert 0o600. + expect(mfs.chmodSync).toHaveBeenCalledWith(CREDENTIALS_PATH, 0o600); + expect(mfs.readFileSync).toHaveBeenCalledWith(CREDENTIALS_PATH, "utf-8"); + }); + + test("returns null on malformed JSON", () => { + mfs.existsSync.mockReturnValue(true); + mfs.readFileSync.mockReturnValue("not json"); + expect(loadTokens()).toBeNull(); + }); + + test("falls back to the legacy file (no throw) when migration fails", () => { + const tokens: TokenData = { access_token: "tok", token_type: "bearer" }; + // Only the legacy file exists; the rename fails (e.g. EXDEV / EACCES). + mfs.existsSync.mockImplementation((filePath) => filePath === LEGACY_CREDENTIALS_PATH); + mfs.renameSync.mockImplementation(() => { + throw new Error("EXDEV: cross-device link not permitted"); + }); + mfs.readFileSync.mockReturnValue(JSON.stringify(tokens)); + + expect(() => loadTokens()).not.toThrow(); + expect(loadTokens()).toEqual(tokens); + expect(mfs.readFileSync).toHaveBeenCalledWith(LEGACY_CREDENTIALS_PATH, "utf-8"); + }); +}); + +describe("clearTokens", () => { + test("deletes file and returns true when it exists", () => { + mfs.existsSync.mockReturnValue(true); + expect(clearTokens()).toBe(true); + expect(mfs.unlinkSync).toHaveBeenCalledWith(CREDENTIALS_PATH); + }); + + test("returns false when file does not exist", () => { + mfs.existsSync.mockReturnValue(false); + expect(clearTokens()).toBe(false); + expect(mfs.unlinkSync).not.toHaveBeenCalled(); + }); +}); + +describe("isTokenExpired", () => { + test("returns false when no expires_at is set", () => { + expect(isTokenExpired({ access_token: "tok", token_type: "bearer" })).toBe(false); + }); + + test("returns false when well before expiry", () => { + expect( + isTokenExpired({ + access_token: "tok", + token_type: "bearer", + expires_at: Date.now() + 120_000, + }) + ).toBe(false); + }); + + test("returns true when past expiry", () => { + expect( + isTokenExpired({ access_token: "tok", token_type: "bearer", expires_at: Date.now() - 1000 }) + ).toBe(true); + }); + + test("returns true within 60s buffer window", () => { + expect( + isTokenExpired({ access_token: "tok", token_type: "bearer", expires_at: Date.now() + 30_000 }) + ).toBe(true); + }); + + test("returns false at exactly 60s before expiry", () => { + const now = 1000000; + vi.spyOn(Date, "now").mockReturnValue(now); + expect( + isTokenExpired({ access_token: "tok", token_type: "bearer", expires_at: now + 60_000 }) + ).toBe(false); + }); +}); + +describe("getValidAccessToken", () => { + test("returns null when no tokens stored", async () => { + mfs.existsSync.mockReturnValue(false); + expect(await getValidAccessToken()).toBeNull(); + }); + + test("returns access_token when not expired", async () => { + const tokens: TokenData = { + access_token: "valid-tok", + token_type: "bearer", + expires_at: Date.now() + 120_000, + }; + mfs.existsSync.mockReturnValue(true); + mfs.readFileSync.mockReturnValue(JSON.stringify(tokens)); + expect(await getValidAccessToken()).toBe("valid-tok"); + }); + + test("returns null when expired and no refresh_token", async () => { + const tokens: TokenData = { + access_token: "expired-tok", + token_type: "bearer", + expires_at: Date.now() - 1000, + }; + mfs.existsSync.mockReturnValue(true); + mfs.readFileSync.mockReturnValue(JSON.stringify(tokens)); + expect(await getValidAccessToken()).toBeNull(); + }); + + test("refreshes token when expired and refresh_token exists", async () => { + const tokens: TokenData = { + access_token: "expired-tok", + token_type: "bearer", + expires_at: Date.now() - 1000, + refresh_token: "refresh-tok", + }; + const newTokens: TokenData = { + access_token: "new-tok", + token_type: "bearer", + expires_in: 3600, + }; + + mfs.existsSync.mockReturnValue(true); + mfs.readFileSync.mockReturnValue(JSON.stringify(tokens)); + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve(newTokens), + }) + ); + + const result = await getValidAccessToken(); + expect(result).toBe("new-tok"); + + expect(fetch).toHaveBeenCalledWith( + "https://test.context7.com/api/oauth/token", + expect.objectContaining({ + method: "POST", + body: expect.stringContaining("grant_type=refresh_token"), + }) + ); + + expect(mfs.writeFileSync).toHaveBeenCalled(); + }); + + test("returns null when refresh fails", async () => { + const tokens: TokenData = { + access_token: "expired-tok", + token_type: "bearer", + expires_at: Date.now() - 1000, + refresh_token: "refresh-tok", + }; + + mfs.existsSync.mockReturnValue(true); + mfs.readFileSync.mockReturnValue(JSON.stringify(tokens)); + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: false, + json: () => Promise.resolve({ error: "invalid_grant" }), + }) + ); + + expect(await getValidAccessToken()).toBeNull(); + }); +}); + +describe("startDeviceAuthorization", () => { + test("returns parsed response on 200", async () => { + const payload = { + device_code: "dc", + user_code: "ABCD-EFGH", + verification_uri: "https://t.example/oauth/device", + verification_uri_complete: "https://t.example/oauth/device?user_code=ABCD-EFGH", + expires_in: 600, + interval: 5, + }; + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ ok: true, json: () => Promise.resolve(payload) }) + ); + await expect(startDeviceAuthorization("https://t.example", "test-client")).resolves.toEqual( + payload + ); + }); + + test("POSTs client_id as form-encoded body", async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => + Promise.resolve({ + device_code: "", + user_code: "", + verification_uri: "", + expires_in: 0, + interval: 5, + }), + }); + vi.stubGlobal("fetch", fetchMock); + await startDeviceAuthorization("https://t.example", "test-client"); + const [url, init] = fetchMock.mock.calls[0]; + expect(url).toBe("https://t.example/api/oauth/device/code"); + expect(init.method).toBe("POST"); + expect(init.headers).toEqual({ "Content-Type": "application/x-www-form-urlencoded" }); + // Body is form-encoded; hostname is appended best-effort and varies by + // machine, so assert on the parsed client_id rather than the exact string. + expect(new URLSearchParams(init.body as string).get("client_id")).toBe("test-client"); + }); + + test("throws with the server-provided error_description", async () => { + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: false, + json: () => + Promise.resolve({ error: "invalid_request", error_description: "bad client_id" }), + }) + ); + await expect(startDeviceAuthorization("https://t", "bogus")).rejects.toThrow("bad client_id"); + }); +}); + +describe("pollDeviceToken", () => { + test("approved on 200 returns tokens", async () => { + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: true, + status: 200, + json: () => Promise.resolve({ access_token: "ctx7sk-x", token_type: "bearer" }), + }) + ); + const result = await pollDeviceToken("https://t", "c", "dc"); + expect(result.status).toBe("approved"); + expect(result.tokens?.access_token).toBe("ctx7sk-x"); + }); + + test.each([ + ["authorization_pending", "pending"], + ["slow_down", "slow_down"], + ["access_denied", "denied"], + ["expired_token", "expired"], + ] as const)("maps %s -> %s", async (serverError, expected) => { + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: false, + status: 400, + json: () => Promise.resolve({ error: serverError }), + }) + ); + expect((await pollDeviceToken("https://t", "c", "dc")).status).toBe(expected); + }); + + test("returns transient on a 5xx response", async () => { + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: false, + status: 503, + json: () => Promise.resolve({ error: "server_error" }), + }) + ); + const result = await pollDeviceToken("https://t", "c", "dc"); + expect(result.status).toBe("transient"); + expect(result.errorMessage).toBeTruthy(); + }); + + test("returns transient on a fetch network failure", async () => { + vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("ECONNREFUSED"))); + const result = await pollDeviceToken("https://t", "c", "dc"); + expect(result.status).toBe("transient"); + expect(result.errorMessage).toBe("ECONNREFUSED"); + }); + + test("throws on unknown 4xx error code", async () => { + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: false, + status: 400, + json: () => + Promise.resolve({ error: "invalid_grant", error_description: "device_code malformed" }), + }) + ); + await expect(pollDeviceToken("https://t", "c", "dc")).rejects.toThrow("device_code malformed"); + }); +}); diff --git a/packages/cli/src/__tests__/find-docs-skill-alignment.test.ts b/packages/cli/src/__tests__/find-docs-skill-alignment.test.ts new file mode 100644 index 0000000..5bd725d --- /dev/null +++ b/packages/cli/src/__tests__/find-docs-skill-alignment.test.ts @@ -0,0 +1,35 @@ +import { describe, test, expect } from "vitest"; +import { readFile } from "fs/promises"; +import { join, dirname } from "path"; +import { fileURLToPath } from "url"; + +const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "../../../.."); +const skillPath = join(repoRoot, "skills/find-docs/SKILL.md"); +const rulePath = join(repoRoot, "rules/context7-cli.md"); + +describe("find-docs skill aligns with context7-cli rule", () => { + test("uses npx ctx7@latest as the canonical invocation style", async () => { + const skill = await readFile(skillPath, "utf-8"); + expect(skill).toContain("npx ctx7@latest library"); + expect(skill).toContain("npx ctx7@latest docs"); + expect(skill).not.toMatch(/^ctx7 library/m); + expect(skill).not.toContain("ctx7 library nextjs"); + }); + + test("documents official library naming guidance", async () => { + const skill = await readFile(skillPath, "utf-8"); + const rule = await readFile(rulePath, "utf-8"); + + expect(skill).toContain('"Next.js" not "nextjs"'); + expect(rule).toContain('"Next.js" not "nextjs"'); + expect(skill).toContain('library "Next.js"'); + }); + + test("does not recommend global install as the primary workflow", async () => { + const skill = await readFile(skillPath, "utf-8"); + const npxIndex = skill.indexOf("npx ctx7@latest"); + const globalInstallIndex = skill.indexOf("npm install -g ctx7@latest"); + expect(npxIndex).toBeGreaterThanOrEqual(0); + expect(globalInstallIndex).toBeGreaterThan(npxIndex); + }); +}); diff --git a/packages/cli/src/__tests__/installer.test.ts b/packages/cli/src/__tests__/installer.test.ts new file mode 100644 index 0000000..daf79d6 --- /dev/null +++ b/packages/cli/src/__tests__/installer.test.ts @@ -0,0 +1,159 @@ +import { afterEach, beforeEach, describe, expect, test } from "vitest"; +import { mkdir, readFile, writeFile, rm, access } from "fs/promises"; +import { join } from "path"; +import { tmpdir } from "os"; + +import { installSkillFiles, symlinkSkill } from "../utils/installer.js"; +import { isSafeSkillName, assertSkillNameInRoot } from "../utils/skill-name.js"; + +let tempDir: string; + +async function exists(path: string): Promise { + try { + await access(path); + return true; + } catch { + return false; + } +} + +beforeEach(async () => { + tempDir = join(tmpdir(), `ctx7-installer-test-${Date.now()}-${Math.random()}`); + await mkdir(tempDir, { recursive: true }); +}); + +afterEach(async () => { + await rm(tempDir, { recursive: true, force: true }); +}); + +describe("isSafeSkillName", () => { + test("accepts typical skill names", () => { + for (const name of [ + "pdf", + "find-docs", + "skill_one", + "skill.v2", + "a1", + "abc123", + "PDF", + "Find-Docs", + "MySkill", + ]) { + expect(isSafeSkillName(name)).toBe(true); + } + }); + + test("rejects path traversal and separators", () => { + for (const name of [ + "..", + ".", + "../evil", + "..\\evil", + "a/b", + "a\\b", + "/abs", + "C:\\drive", + "with space", + "", + ".hidden", + "name\0", + "name\nwith-newline", + ]) { + expect(isSafeSkillName(name)).toBe(false); + } + }); + + test("rejects names longer than 128 chars", () => { + expect(isSafeSkillName("a".repeat(128))).toBe(true); + expect(isSafeSkillName("a".repeat(129))).toBe(false); + }); +}); + +describe("assertSkillNameInRoot", () => { + test("returns resolved path for safe name", () => { + const result = assertSkillNameInRoot("/tmp/skills", "pdf"); + expect(result).toBe("/tmp/skills/pdf"); + }); + + test("throws on traversal", () => { + expect(() => assertSkillNameInRoot("/tmp/skills", "..")).toThrow(); + expect(() => assertSkillNameInRoot("/tmp/skills", "../evil")).toThrow(); + }); +}); + +describe("installSkillFiles", () => { + test("writes files inside the skill directory", async () => { + const skillsRoot = join(tempDir, "skills"); + await mkdir(skillsRoot, { recursive: true }); + + await installSkillFiles("good", [{ path: "SKILL.md", content: "hello" }], skillsRoot); + + const written = await readFile(join(skillsRoot, "good", "SKILL.md"), "utf8"); + expect(written).toBe("hello"); + }); + + test("rejects skill name '..' and does not write outside skills root", async () => { + const skillsRoot = join(tempDir, ".claude", "skills"); + await mkdir(skillsRoot, { recursive: true }); + + const settingsPath = join(tempDir, ".claude", "settings.json"); + + await expect( + installSkillFiles("..", [{ path: "settings.json", content: '{"hooks":{}}' }], skillsRoot) + ).rejects.toThrow(); + + expect(await exists(settingsPath)).toBe(false); + }); + + test("rejects skill names with path separators", async () => { + const skillsRoot = join(tempDir, "skills"); + await mkdir(skillsRoot, { recursive: true }); + + for (const bad of ["../evil", "a/b", "..\\evil"]) { + await expect( + installSkillFiles(bad, [{ path: "SKILL.md", content: "x" }], skillsRoot) + ).rejects.toThrow(); + } + }); + + test("still rejects traversal in file.path", async () => { + const skillsRoot = join(tempDir, "skills"); + await mkdir(skillsRoot, { recursive: true }); + + await expect( + installSkillFiles("good", [{ path: "../escape.txt", content: "x" }], skillsRoot) + ).rejects.toThrow(/outside/); + }); +}); + +describe("symlinkSkill", () => { + test("creates symlink under skills root for safe name", async () => { + const skillsRoot = join(tempDir, "linked"); + await mkdir(skillsRoot, { recursive: true }); + + const source = join(tempDir, "source"); + await mkdir(source, { recursive: true }); + await writeFile(join(source, "marker"), "ok"); + + await symlinkSkill("good", source, skillsRoot); + + const linkedMarker = await readFile(join(skillsRoot, "good", "marker"), "utf8"); + expect(linkedMarker).toBe("ok"); + }); + + test("does not rm parent when skill name is '..'", async () => { + const skillsRoot = join(tempDir, ".cursor", "skills"); + await mkdir(skillsRoot, { recursive: true }); + + const sentinel = join(tempDir, ".cursor", "keep.txt"); + await writeFile(sentinel, "sentinel"); + + const source = join(tempDir, "source"); + await mkdir(source, { recursive: true }); + + await expect(symlinkSkill("..", source, skillsRoot)).rejects.toThrow(); + + expect(await exists(sentinel)).toBe(true); + expect(await exists(join(tempDir, ".cursor"))).toBe(true); + }); +}); diff --git a/packages/cli/src/__tests__/library-id.test.ts b/packages/cli/src/__tests__/library-id.test.ts new file mode 100644 index 0000000..13f75d2 --- /dev/null +++ b/packages/cli/src/__tests__/library-id.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, test } from "vitest"; + +import { recoverLibraryId } from "../utils/library-id.js"; + +describe("recoverLibraryId", () => { + test("passes through a normal library ID unchanged", () => { + expect(recoverLibraryId("/facebook/react")).toBe("/facebook/react"); + expect(recoverLibraryId("/vercel/next.js/v15.1.8")).toBe("/vercel/next.js/v15.1.8"); + }); + + test("recovers a Git Bash mangled path (default install dir)", () => { + expect(recoverLibraryId("C:/Program Files/Git/facebook/react")).toBe("/facebook/react"); + }); + + test("recovers a mangled path with backslashes", () => { + expect(recoverLibraryId("C:\\Program Files\\Git\\facebook\\react")).toBe("/facebook/react"); + }); + + test("preserves a version segment", () => { + expect(recoverLibraryId("C:/Program Files/Git/vercel/next.js/v15.1.8")).toBe( + "/vercel/next.js/v15.1.8" + ); + }); + + test("recovers from a portable Git install", () => { + expect(recoverLibraryId("D:/tools/PortableGit/facebook/react")).toBe("/facebook/react"); + }); + + test("recovers an owner that looks like a system dir", () => { + expect(recoverLibraryId("C:/Program Files/Git/usr/some-repo")).toBe("/usr/some-repo"); + }); + + test("collapses the leading double-slash workaround", () => { + expect(recoverLibraryId("//facebook/react")).toBe("/facebook/react"); + }); + + test("leaves a non-Windows-path argument untouched", () => { + expect(recoverLibraryId("facebook/react")).toBe("facebook/react"); + }); + + test("leaves an unrecognized Windows path untouched", () => { + expect(recoverLibraryId("C:/Users/me/project")).toBe("C:/Users/me/project"); + }); +}); diff --git a/packages/cli/src/__tests__/remove.test.ts b/packages/cli/src/__tests__/remove.test.ts new file mode 100644 index 0000000..59d7f85 --- /dev/null +++ b/packages/cli/src/__tests__/remove.test.ts @@ -0,0 +1,357 @@ +import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"; +import { Command } from "commander"; +import { mkdir, readFile, writeFile, rm, access } from "fs/promises"; +import { join } from "path"; +import { tmpdir } from "os"; + +const trackEvent = vi.fn(); +const mockCheckboxWithHover = vi.fn(); +let logOutput: string[]; + +vi.mock("../utils/tracking.js", () => ({ + trackEvent: (...args: unknown[]) => trackEvent(...args), +})); + +vi.mock("../utils/prompts.js", () => ({ + checkboxWithHover: (...args: unknown[]) => mockCheckboxWithHover(...args), +})); + +const mockSpinner = { + start: vi.fn().mockReturnThis(), + stop: vi.fn().mockReturnThis(), + succeed: vi.fn().mockReturnThis(), + fail: vi.fn().mockReturnThis(), + text: "", +}; +vi.mock("ora", () => ({ default: () => mockSpinner })); + +import { registerRemoveCommand } from "../commands/remove.js"; + +let tempDir: string; +let originalCwd: string; + +async function exists(path: string): Promise { + try { + await access(path); + return true; + } catch { + return false; + } +} + +async function runCommand(...args: string[]): Promise { + const program = new Command(); + program.exitOverride(); + registerRemoveCommand(program); + await program.parseAsync(["node", "test", ...args]); +} + +beforeEach(async () => { + vi.clearAllMocks(); + logOutput = []; + vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => { + logOutput.push(args.join(" ")); + }); + vi.spyOn(console, "error").mockImplementation(() => {}); + originalCwd = process.cwd(); + tempDir = join(tmpdir(), `ctx7-uninstall-${Date.now()}`); + await mkdir(tempDir, { recursive: true }); + process.chdir(tempDir); +}); + +afterEach(async () => { + process.chdir(originalCwd); + await rm(tempDir, { recursive: true, force: true }); + vi.restoreAllMocks(); +}); + +describe("remove command", () => { + test("removes only CLI artifacts for cursor project setup", async () => { + const rulePath = join(tempDir, ".cursor", "rules", "context7.mdc"); + const cliSkillPath = join(tempDir, ".cursor", "skills", "find-docs", "SKILL.md"); + const mcpSkillPath = join(tempDir, ".cursor", "skills", "context7-mcp", "SKILL.md"); + + await mkdir(join(tempDir, ".cursor", "rules"), { recursive: true }); + await mkdir(join(tempDir, ".cursor", "skills", "find-docs"), { recursive: true }); + await mkdir(join(tempDir, ".cursor", "skills", "context7-mcp"), { recursive: true }); + await writeFile(rulePath, "cursor rule", "utf-8"); + await writeFile(cliSkillPath, "find docs", "utf-8"); + await writeFile(mcpSkillPath, "mcp skill", "utf-8"); + + await runCommand("remove", "--cursor", "--cli", "--project"); + + expect(await exists(rulePath)).toBe(false); + expect(await exists(join(tempDir, ".cursor", "skills", "find-docs"))).toBe(false); + expect(await exists(mcpSkillPath)).toBe(true); + expect(trackEvent).toHaveBeenCalledWith("command", { name: "remove" }); + expect(trackEvent).toHaveBeenCalledWith("remove", { + agents: ["cursor"], + scope: "project", + modes: ["cli"], + }); + }); + + test("removes only MCP artifacts for codex project setup", async () => { + const agentsPath = join(tempDir, "AGENTS.md"); + const tomlPath = join(tempDir, ".codex", "config.toml"); + const mcpSkillPath = join(tempDir, ".agents", "skills", "context7-mcp", "SKILL.md"); + const cliSkillPath = join(tempDir, ".agents", "skills", "find-docs", "SKILL.md"); + + await mkdir(join(tempDir, ".codex"), { recursive: true }); + await mkdir(join(tempDir, ".agents", "skills", "context7-mcp"), { recursive: true }); + await mkdir(join(tempDir, ".agents", "skills", "find-docs"), { recursive: true }); + await writeFile( + agentsPath, + "# Before\n\n\nrule body\n\n", + "utf-8" + ); + await writeFile( + tomlPath, + 'model = "gpt-5"\n\n[mcp_servers.context7]\nurl = "https://mcp.context7.com/mcp"\n\n[mcp_servers.other]\nurl = "https://other.com"\n', + "utf-8" + ); + await writeFile(mcpSkillPath, "mcp skill", "utf-8"); + await writeFile(cliSkillPath, "find docs", "utf-8"); + + await runCommand("remove", "--codex", "--mcp", "--project"); + + const agentsContent = await readFile(agentsPath, "utf-8"); + const tomlContent = await readFile(tomlPath, "utf-8"); + + expect(agentsContent).not.toContain(""); + expect(tomlContent).toContain("[mcp_servers.other]"); + expect(tomlContent).not.toContain("[mcp_servers.context7]"); + expect(await exists(join(tempDir, ".agents", "skills", "context7-mcp"))).toBe(false); + expect(await exists(cliSkillPath)).toBe(true); + expect(trackEvent).toHaveBeenCalledWith("remove", { + agents: ["codex"], + scope: "project", + modes: ["mcp"], + }); + }); + + test("supports uninstall alias and --all to remove both setup modes", async () => { + const agentsPath = join(tempDir, "AGENTS.md"); + const tomlPath = join(tempDir, ".codex", "config.toml"); + const mcpSkillPath = join(tempDir, ".agents", "skills", "context7-mcp", "SKILL.md"); + const cliSkillPath = join(tempDir, ".agents", "skills", "find-docs", "SKILL.md"); + + await mkdir(join(tempDir, ".codex"), { recursive: true }); + await mkdir(join(tempDir, ".agents", "skills", "context7-mcp"), { recursive: true }); + await mkdir(join(tempDir, ".agents", "skills", "find-docs"), { recursive: true }); + await writeFile( + agentsPath, + "# Before\n\n\nrule body\n\n", + "utf-8" + ); + await writeFile( + tomlPath, + '[mcp_servers.context7]\nurl = "https://mcp.context7.com/mcp"\n', + "utf-8" + ); + await writeFile(mcpSkillPath, "mcp skill", "utf-8"); + await writeFile(cliSkillPath, "find docs", "utf-8"); + + await runCommand("uninstall", "--codex", "--all", "--project"); + + const agentsContent = await readFile(agentsPath, "utf-8"); + expect(agentsContent).not.toContain(""); + expect(await exists(join(tempDir, ".agents", "skills", "context7-mcp"))).toBe(false); + expect(await exists(join(tempDir, ".agents", "skills", "find-docs"))).toBe(false); + expect(await readFile(tomlPath, "utf-8")).not.toContain("[mcp_servers.context7]"); + expect(trackEvent).toHaveBeenCalledWith("remove", { + agents: ["codex"], + scope: "project", + modes: ["mcp", "cli"], + }); + }); + + test("skips mode prompt when only one setup mode exists", async () => { + const rulePath = join(tempDir, ".cursor", "rules", "context7.mdc"); + const cliSkillPath = join(tempDir, ".cursor", "skills", "find-docs", "SKILL.md"); + const mcpSkillPath = join(tempDir, ".cursor", "skills", "context7-mcp", "SKILL.md"); + + await mkdir(join(tempDir, ".cursor", "rules"), { recursive: true }); + await mkdir(join(tempDir, ".cursor", "skills", "find-docs"), { recursive: true }); + await mkdir(join(tempDir, ".cursor", "skills", "context7-mcp"), { recursive: true }); + await writeFile(rulePath, "cursor rule", "utf-8"); + await writeFile(cliSkillPath, "find docs", "utf-8"); + await writeFile(mcpSkillPath, "mcp skill", "utf-8"); + + await rm(join(tempDir, ".cursor", "skills", "context7-mcp"), { recursive: true }); + + await runCommand("remove", "--cursor", "--project"); + + expect(mockCheckboxWithHover).not.toHaveBeenCalled(); + expect(await exists(rulePath)).toBe(false); + expect(await exists(join(tempDir, ".cursor", "skills", "find-docs"))).toBe(false); + expect(await exists(mcpSkillPath)).toBe(false); + expect(trackEvent).toHaveBeenCalledWith("remove", { + agents: ["cursor"], + scope: "project", + modes: ["cli"], + }); + }); + + test("prompts for setup mode when both MCP and CLI artifacts exist", async () => { + const agentsPath = join(tempDir, "AGENTS.md"); + const tomlPath = join(tempDir, ".codex", "config.toml"); + const mcpSkillPath = join(tempDir, ".agents", "skills", "context7-mcp", "SKILL.md"); + const cliSkillPath = join(tempDir, ".agents", "skills", "find-docs", "SKILL.md"); + + await mkdir(join(tempDir, ".codex"), { recursive: true }); + await mkdir(join(tempDir, ".agents", "skills", "context7-mcp"), { recursive: true }); + await mkdir(join(tempDir, ".agents", "skills", "find-docs"), { recursive: true }); + await writeFile( + agentsPath, + "# Before\n\n\nrule body\n\n", + "utf-8" + ); + await writeFile( + tomlPath, + '[mcp_servers.context7]\nurl = "https://mcp.context7.com/mcp"\n', + "utf-8" + ); + await writeFile(mcpSkillPath, "mcp skill", "utf-8"); + await writeFile(cliSkillPath, "find docs", "utf-8"); + mockCheckboxWithHover.mockResolvedValueOnce(["cli"]); + + await runCommand("remove", "--codex", "--project"); + + expect(mockCheckboxWithHover).toHaveBeenCalledTimes(1); + expect(mockCheckboxWithHover.mock.calls[0]?.[0]).toMatchObject({ + message: "Which Context7 setup modes do you want to remove?", + }); + expect(await exists(join(tempDir, ".agents", "skills", "find-docs"))).toBe(false); + expect(await exists(mcpSkillPath)).toBe(true); + expect(await readFile(tomlPath, "utf-8")).toContain("[mcp_servers.context7]"); + expect(trackEvent).toHaveBeenCalledWith("remove", { + agents: ["codex"], + scope: "project", + modes: ["cli"], + }); + }); + + test("does not log not found items when other artifacts were removed", async () => { + const agentsPath = join(tempDir, "AGENTS.md"); + const tomlPath = join(tempDir, ".codex", "config.toml"); + const mcpSkillPath = join(tempDir, ".agents", "skills", "context7-mcp", "SKILL.md"); + + await mkdir(join(tempDir, ".codex"), { recursive: true }); + await mkdir(join(tempDir, ".agents", "skills", "context7-mcp"), { recursive: true }); + await writeFile( + agentsPath, + "# Before\n\n\nrule body\n\n", + "utf-8" + ); + await writeFile( + tomlPath, + '[mcp_servers.context7]\nurl = "https://mcp.context7.com/mcp"\n', + "utf-8" + ); + await writeFile(mcpSkillPath, "mcp skill", "utf-8"); + + await runCommand("remove", "--codex", "--all", "--project"); + + expect(logOutput.some((line) => line.includes("MCP config removed"))).toBe(true); + expect(logOutput.some((line) => line.includes("Rule removed"))).toBe(true); + expect(logOutput.some((line) => line.includes("Skill context7-mcp removed"))).toBe(true); + expect(logOutput.some((line) => line.includes("not found"))).toBe(false); + }); + + test("removes only context7 from cursor JSON MCP config", async () => { + const mcpPath = join(tempDir, ".cursor", "mcp.json"); + + await mkdir(join(tempDir, ".cursor"), { recursive: true }); + await writeFile( + mcpPath, + JSON.stringify( + { + theme: "dark", + mcpServers: { + alpha: { url: "https://alpha.com" }, + context7: { url: "https://mcp.context7.com/mcp" }, + omega: { url: "https://omega.com" }, + }, + telemetry: { enabled: true }, + }, + null, + 2 + ), + "utf-8" + ); + + await runCommand("remove", "--cursor", "--mcp", "--project"); + + expect(JSON.parse(await readFile(mcpPath, "utf-8"))).toEqual({ + theme: "dark", + mcpServers: { + alpha: { url: "https://alpha.com" }, + omega: { url: "https://omega.com" }, + }, + telemetry: { enabled: true }, + }); + }); + + test("removes only context7 from opencode JSONC MCP config", async () => { + const configPath = join(tempDir, "opencode.jsonc"); + + await writeFile( + configPath, + `{ + // keep this file functional after removing Context7 + "theme": "night", + "mcp": { + "alpha": { "type": "remote", "url": "https://alpha.com", "enabled": true }, + "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "enabled": true }, + "omega": { "type": "remote", "url": "https://omega.com", "enabled": false } + }, + "telemetry": { "enabled": true } +} +`, + "utf-8" + ); + + await runCommand("remove", "--opencode", "--mcp", "--project"); + + expect(JSON.parse(await readFile(configPath, "utf-8"))).toEqual({ + theme: "night", + mcp: { + alpha: { type: "remote", url: "https://alpha.com", enabled: true }, + omega: { type: "remote", url: "https://omega.com", enabled: false }, + }, + telemetry: { enabled: true }, + }); + }); + + test("detects only agents with Context7 artifacts, not just agent folders", async () => { + const rulePath = join(tempDir, ".cursor", "rules", "context7.mdc"); + const cliSkillPath = join(tempDir, ".cursor", "skills", "find-docs", "SKILL.md"); + + await mkdir(join(tempDir, ".cursor", "rules"), { recursive: true }); + await mkdir(join(tempDir, ".cursor", "skills", "find-docs"), { recursive: true }); + await mkdir(join(tempDir, ".gemini"), { recursive: true }); + await writeFile(rulePath, "cursor rule", "utf-8"); + await writeFile(cliSkillPath, "find docs", "utf-8"); + mockCheckboxWithHover.mockResolvedValueOnce(["cursor"]); + + await runCommand("remove", "--project"); + + expect(logOutput.some((line) => line.includes("Detected: Cursor"))).toBe(true); + expect(logOutput.some((line) => line.includes("Gemini CLI"))).toBe(false); + expect(mockCheckboxWithHover.mock.calls[0]?.[0]).toMatchObject({ + message: "Which agents do you want to remove Context7 setup from?", + choices: [{ name: "Cursor", value: "cursor" }], + }); + }); + + test("does not prompt when no Context7 setup is detected", async () => { + await mkdir(join(tempDir, ".gemini"), { recursive: true }); + await writeFile(join(tempDir, ".gemini", "settings.json"), "{}", "utf-8"); + + await runCommand("remove", "--project"); + + expect(mockCheckboxWithHover).not.toHaveBeenCalled(); + expect(logOutput.some((line) => line.includes("No Context7 setup detected"))).toBe(true); + }); +}); diff --git a/packages/cli/src/__tests__/setup.test.ts b/packages/cli/src/__tests__/setup.test.ts new file mode 100644 index 0000000..dd77ea1 --- /dev/null +++ b/packages/cli/src/__tests__/setup.test.ts @@ -0,0 +1,1313 @@ +import { describe, test, expect, vi, beforeEach, afterEach } from "vitest"; +import { mkdir, readFile, writeFile, rm } from "fs/promises"; +import { join } from "path"; +import { tmpdir } from "os"; + +const MOCK_MCP_RULE = "Use Context7 MCP to fetch docs.\n"; +const MOCK_CLI_RULE = "Use the `ctx7` CLI to fetch docs.\n"; + +vi.stubGlobal( + "fetch", + vi.fn((url: string) => { + if (url.includes("context7-mcp.md")) { + return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_MCP_RULE) }); + } + if (url.includes("context7-cli.md")) { + return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_CLI_RULE) }); + } + return Promise.resolve({ ok: false }); + }) +); + +import { getRuleContent } from "../setup/templates.js"; +import { + mergeServerEntry, + removeServerEntry, + readJsonConfig, + writeJsonConfig, + readTomlServerExists, + readTomlServerEntry, + buildTomlServerBlock, + appendTomlServer, + removeTomlServer, + resolveMcpPath, + isStdioContext7Entry, + patchStdioApiKey, +} from "../setup/mcp-writer.js"; +import { getAgent, ALL_AGENT_NAMES, type AuthOptions } from "../setup/agents.js"; + +describe("getRuleContent", () => { + test("returns correct content per mode", async () => { + expect(await getRuleContent("mcp", "claude")).toBe(MOCK_MCP_RULE); + expect(await getRuleContent("cli", "claude")).toBe(MOCK_CLI_RULE); + }); + + test("only cursor gets alwaysApply frontmatter", async () => { + const cursor = await getRuleContent("mcp", "cursor"); + expect(cursor).toContain("---\nalwaysApply: true\n---"); + expect(cursor).toContain(MOCK_MCP_RULE); + + for (const agent of ["claude", "antigravity", "codex", "opencode", "gemini"]) { + const content = await getRuleContent("mcp", agent); + expect(content).not.toContain("alwaysApply"); + } + }); + + test("returns fallback content when all fetch URLs fail", async () => { + vi.stubGlobal( + "fetch", + vi.fn(() => Promise.resolve({ ok: false })) + ); + const content = await getRuleContent("mcp", "claude"); + expect(content).toContain("Context7 MCP"); + expect(content.length).toBeGreaterThan(100); + + vi.stubGlobal( + "fetch", + vi.fn((url: string) => { + if (url.includes("context7-mcp.md")) + return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_MCP_RULE) }); + if (url.includes("context7-cli.md")) + return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_CLI_RULE) }); + return Promise.resolve({ ok: false }); + }) + ); + }); +}); + +describe("mergeServerEntry", () => { + test("adds server to empty config", () => { + const { config, alreadyExists } = mergeServerEntry({}, "mcpServers", "context7", { + url: "https://mcp.context7.com/mcp", + }); + expect(alreadyExists).toBe(false); + expect((config.mcpServers as Record).context7).toEqual({ + url: "https://mcp.context7.com/mcp", + }); + }); + + test("preserves existing servers when adding new one", () => { + const { config } = mergeServerEntry( + { mcpServers: { other: { url: "https://other.com" } } }, + "mcpServers", + "context7", + { url: "https://mcp.context7.com/mcp" } + ); + const servers = config.mcpServers as Record; + expect(servers.context7).toBeTruthy(); + expect(servers.other).toEqual({ url: "https://other.com" }); + }); + + test("overwrites existing server and flags alreadyExists", () => { + const existing = { mcpServers: { context7: { url: "https://old.com" } } }; + const { config, alreadyExists } = mergeServerEntry(existing, "mcpServers", "context7", { + url: "https://new.com", + }); + expect(alreadyExists).toBe(true); + expect((config.mcpServers as Record).context7).toEqual({ + url: "https://new.com", + }); + }); + + test("overwrites existing server entry with new url", () => { + const existing = { + mcpServers: { + context7: { url: "https://old.com", headers: { key: "old-key" } }, + other: { url: "https://other.com" }, + }, + }; + const { config, alreadyExists } = mergeServerEntry(existing, "mcpServers", "context7", { + url: "https://mcp.context7.com/mcp", + headers: { key: "new-key" }, + }); + expect(alreadyExists).toBe(true); + const servers = config.mcpServers as Record; + expect(servers.context7).toEqual({ + url: "https://mcp.context7.com/mcp", + headers: { key: "new-key" }, + }); + expect(servers.other).toEqual({ url: "https://other.com" }); + }); + + test("overwrites existing server entry with different auth mode", () => { + const existing = { + mcpServers: { + context7: { url: "https://mcp.context7.com/mcp", headers: { "x-api-key": "old" } }, + }, + }; + const { config, alreadyExists } = mergeServerEntry(existing, "mcpServers", "context7", { + url: "https://mcp.context7.com/mcp", + }); + expect(alreadyExists).toBe(true); + expect((config.mcpServers as Record).context7).toEqual({ + url: "https://mcp.context7.com/mcp", + }); + }); + + test("works with opencode configKey 'mcp'", () => { + const { config } = mergeServerEntry({}, "mcp", "context7", { + type: "remote", + url: "https://mcp.context7.com/mcp", + }); + expect((config.mcp as Record).context7).toEqual({ + type: "remote", + url: "https://mcp.context7.com/mcp", + }); + }); +}); + +describe("removeServerEntry", () => { + test("removes server from config section", () => { + const { config, removed } = removeServerEntry( + { + mcpServers: { + context7: { url: "https://mcp.context7.com/mcp" }, + other: { url: "https://other.com" }, + }, + }, + "mcpServers", + "context7" + ); + + expect(removed).toBe(true); + expect(config).toEqual({ + mcpServers: { + other: { url: "https://other.com" }, + }, + }); + }); + + test("removes empty config section when context7 is the only server", () => { + const { config, removed } = removeServerEntry( + { + mcpServers: { + context7: { url: "https://mcp.context7.com/mcp" }, + }, + theme: "dark", + }, + "mcpServers", + "context7" + ); + + expect(removed).toBe(true); + expect(config).toEqual({ theme: "dark" }); + }); + + test("returns original config when server is not present", () => { + const existing = { mcpServers: { other: { url: "https://other.com" } } }; + const { config, removed } = removeServerEntry(existing, "mcpServers", "context7"); + + expect(removed).toBe(false); + expect(config).toEqual(existing); + }); + + test("preserves unrelated top-level fields and sibling MCP servers", () => { + const existing = { + version: 2, + theme: "dark", + mcpServers: { + alpha: { url: "https://alpha.com" }, + context7: { url: "https://mcp.context7.com/mcp", headers: { key: "secret" } }, + omega: { url: "https://omega.com" }, + }, + telemetry: { enabled: true }, + }; + + const { config, removed } = removeServerEntry(existing, "mcpServers", "context7"); + + expect(removed).toBe(true); + expect(config).toEqual({ + version: 2, + theme: "dark", + mcpServers: { + alpha: { url: "https://alpha.com" }, + omega: { url: "https://omega.com" }, + }, + telemetry: { enabled: true }, + }); + }); +}); + +describe("readJsonConfig / writeJsonConfig", () => { + let tempDir: string; + + beforeEach(async () => { + tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`); + await mkdir(tempDir, { recursive: true }); + }); + + afterEach(async () => { + await rm(tempDir, { recursive: true, force: true }); + }); + + test("returns empty object for missing or empty file", async () => { + expect(await readJsonConfig(join(tempDir, "nope.json"))).toEqual({}); + + await writeFile(join(tempDir, "empty.json"), "", "utf-8"); + expect(await readJsonConfig(join(tempDir, "empty.json"))).toEqual({}); + }); + + test("roundtrip write then read preserves data", async () => { + const path = join(tempDir, "sub", "dir", "config.json"); + const data = { mcpServers: { context7: { url: "https://mcp.context7.com/mcp" } } }; + + await writeJsonConfig(path, data); + const result = await readJsonConfig(path); + expect(result).toEqual(data); + + const raw = await readFile(path, "utf-8"); + expect(raw.endsWith("\n")).toBe(true); + }); +}); + +describe("JSONC support", () => { + let tempDir: string; + + beforeEach(async () => { + tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`); + await mkdir(tempDir, { recursive: true }); + }); + + afterEach(async () => { + await rm(tempDir, { recursive: true, force: true }); + }); + + test("readJsonConfig strips comments without corrupting URLs", async () => { + const path = join(tempDir, "config.jsonc"); + await writeFile( + path, + `{ + // This is a comment + "mcp": {}, + "$schema": "https://opencode.ai/config.json" +}`, + "utf-8" + ); + const result = await readJsonConfig(path); + expect(result.$schema).toBe("https://opencode.ai/config.json"); + expect(result.mcp).toEqual({}); + }); + + test("readJsonConfig handles block comments", async () => { + const path = join(tempDir, "config.jsonc"); + await writeFile(path, '{ /* block */ "key": "value" }', "utf-8"); + const result = await readJsonConfig(path); + expect(result.key).toBe("value"); + }); + + test("resolveMcpPath returns first existing candidate", async () => { + const jsoncPath = join(tempDir, "opencode.jsonc"); + await writeFile(jsoncPath, "{}", "utf-8"); + const resolved = await resolveMcpPath([join(tempDir, "opencode.json"), jsoncPath]); + expect(resolved).toBe(jsoncPath); + }); + + test("resolveMcpPath falls back to first candidate when none exist", async () => { + const jsonPath = join(tempDir, "opencode.json"); + const resolved = await resolveMcpPath([jsonPath]); + expect(resolved).toBe(jsonPath); + }); + + test("resolveMcpPath returns single candidate unchanged", async () => { + const tomlPath = join(tempDir, "config.toml"); + const resolved = await resolveMcpPath([tomlPath]); + expect(resolved).toBe(tomlPath); + }); +}); + +describe("TOML config", () => { + let tempDir: string; + + beforeEach(async () => { + tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`); + await mkdir(tempDir, { recursive: true }); + }); + + afterEach(async () => { + await rm(tempDir, { recursive: true, force: true }); + }); + + test("buildTomlServerBlock generates correct TOML", () => { + const block = buildTomlServerBlock("context7", { + url: "https://mcp.context7.com/mcp", + }); + expect(block).toContain("[mcp_servers.context7]"); + expect(block).toContain('url = "https://mcp.context7.com/mcp"'); + }); + + test("buildTomlServerBlock includes http_headers", () => { + const block = buildTomlServerBlock("context7", { + url: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test" }, + }); + expect(block).toContain("[mcp_servers.context7]"); + expect(block).toContain("[mcp_servers.context7.http_headers]"); + expect(block).toContain('CONTEXT7_API_KEY = "sk-test"'); + expect(block).not.toContain("headers ="); + }); + + test("readTomlServerExists detects existing server", async () => { + const path = join(tempDir, "config.toml"); + await writeFile(path, '[mcp_servers.context7]\nurl = "https://test.com"\n', "utf-8"); + expect(await readTomlServerExists(path, "context7")).toBe(true); + expect(await readTomlServerExists(path, "other")).toBe(false); + }); + + test("readTomlServerExists returns false for missing file", async () => { + expect(await readTomlServerExists(join(tempDir, "nope.toml"), "context7")).toBe(false); + }); + + test("appendTomlServer appends to empty file", async () => { + const path = join(tempDir, "config.toml"); + const { alreadyExists } = await appendTomlServer(path, "context7", { + url: "https://mcp.context7.com/mcp", + }); + expect(alreadyExists).toBe(false); + const content = await readFile(path, "utf-8"); + expect(content).toContain("[mcp_servers.context7]"); + expect(content).toContain('url = "https://mcp.context7.com/mcp"'); + }); + + test("appendTomlServer preserves existing config", async () => { + const path = join(tempDir, "config.toml"); + await writeFile(path, 'model = "gpt-5"\n\n[mcp_servers.other]\nurl = "https://other.com"\n'); + await appendTomlServer(path, "context7", { url: "https://mcp.context7.com/mcp" }); + const content = await readFile(path, "utf-8"); + expect(content).toContain('model = "gpt-5"'); + expect(content).toContain("[mcp_servers.other]"); + expect(content).toContain("[mcp_servers.context7]"); + }); + + test("appendTomlServer is idempotent", async () => { + const path = join(tempDir, "config.toml"); + await appendTomlServer(path, "context7", { url: "https://mcp.context7.com/mcp" }); + const { alreadyExists } = await appendTomlServer(path, "context7", { + url: "https://mcp.context7.com/mcp", + }); + expect(alreadyExists).toBe(true); + const content = await readFile(path, "utf-8"); + expect(content.match(/\[mcp_servers\.context7\]/g)?.length).toBe(1); + }); + + test("appendTomlServer overwrites existing server with new url", async () => { + const path = join(tempDir, "config.toml"); + await appendTomlServer(path, "context7", { url: "https://old.com" }); + const { alreadyExists } = await appendTomlServer(path, "context7", { + url: "https://mcp.context7.com/mcp", + }); + expect(alreadyExists).toBe(true); + const content = await readFile(path, "utf-8"); + expect(content.match(/\[mcp_servers\.context7\]/g)?.length).toBe(1); + expect(content).toContain('url = "https://mcp.context7.com/mcp"'); + expect(content).not.toContain("https://old.com"); + }); + + test("appendTomlServer overwrites server without affecting other servers", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + '[mcp_servers.context7]\nurl = "https://old.com"\n\n[mcp_servers.other]\nurl = "https://other.com"\n' + ); + await appendTomlServer(path, "context7", { url: "https://mcp.context7.com/mcp" }); + const content = await readFile(path, "utf-8"); + expect(content).toContain('url = "https://mcp.context7.com/mcp"'); + expect(content).not.toContain("https://old.com"); + expect(content).toContain("[mcp_servers.other]"); + expect(content).toContain('url = "https://other.com"'); + }); + + test("appendTomlServer overwrites server that appears before non-mcp sections", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + 'model = "gpt-5"\n\n[mcp_servers.context7]\nurl = "https://old.com"\n\n[some_other_section]\nkey = "value"\n' + ); + await appendTomlServer(path, "context7", { + url: "https://mcp.context7.com/mcp", + headers: { "x-api-key": "sk-new" }, + }); + const content = await readFile(path, "utf-8"); + expect(content).toContain('model = "gpt-5"'); + expect(content).toContain('url = "https://mcp.context7.com/mcp"'); + expect(content).toContain("[mcp_servers.context7.http_headers]"); + expect(content).toContain('x-api-key = "sk-new"'); + expect(content).not.toContain("https://old.com"); + expect(content).toContain("[some_other_section]"); + expect(content).toContain('key = "value"'); + }); + + test("appendTomlServer overwrites server at end of file", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + '[mcp_servers.other]\nurl = "https://other.com"\n\n[mcp_servers.context7]\nurl = "https://old.com"\n' + ); + await appendTomlServer(path, "context7", { url: "https://new.com" }); + const content = await readFile(path, "utf-8"); + expect(content).toContain("[mcp_servers.other]"); + expect(content).toContain('url = "https://new.com"'); + expect(content).not.toContain("https://old.com"); + expect(content.match(/\[mcp_servers\.context7\]/g)?.length).toBe(1); + }); + + test("appendTomlServer does not accumulate blank lines on repeated overwrites", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + 'model = "o3"\n\n[mcp_servers.context7]\nurl = "https://old.com"\n\n[mcp_servers.other]\nurl = "https://other.com"\n' + ); + + for (let i = 1; i <= 3; i++) { + await appendTomlServer(path, "context7", { url: `https://v${i}.com` }); + } + + const content = await readFile(path, "utf-8"); + expect(content.match(/\[mcp_servers\.context7\]/g)?.length).toBe(1); + expect(content).toContain('url = "https://v3.com"'); + expect(content).toContain("[mcp_servers.other]"); + expect(content).not.toContain("\n\n\n"); + }); + + test("removeTomlServer removes only the target server", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + 'model = "gpt-5"\n\n[mcp_servers.context7]\nurl = "https://mcp.context7.com/mcp"\n\n[mcp_servers.other]\nurl = "https://other.com"\n', + "utf-8" + ); + + const { removed } = await removeTomlServer(path, "context7"); + expect(removed).toBe(true); + + const content = await readFile(path, "utf-8"); + expect(content).toContain('model = "gpt-5"'); + expect(content).toContain("[mcp_servers.other]"); + expect(content).toContain('url = "https://other.com"'); + expect(content).not.toContain("[mcp_servers.context7]"); + }); + + test("removeTomlServer removes nested subsections too", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + '[mcp_servers.context7]\nurl = "https://mcp.context7.com/mcp"\n\n[mcp_servers.context7.http_headers]\nCONTEXT7_API_KEY = "sk-test"\n\n[settings]\nmodel = "gpt-5"\n', + "utf-8" + ); + + const { removed } = await removeTomlServer(path, "context7"); + expect(removed).toBe(true); + + const content = await readFile(path, "utf-8"); + expect(content).toContain("[settings]"); + expect(content).toContain('model = "gpt-5"'); + expect(content).not.toContain("[mcp_servers.context7]"); + expect(content).not.toContain("CONTEXT7_API_KEY"); + }); + + test("removeTomlServer preserves other MCP servers and their subsections", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + '[mcp_servers.context7]\nurl = "https://mcp.context7.com/mcp"\n\n[mcp_servers.context7.http_headers]\nCONTEXT7_API_KEY = "sk-test"\n\n[mcp_servers.other]\nurl = "https://other.com"\n\n[mcp_servers.other.http_headers]\nX_API_KEY = "keep-me"\n\n[settings]\nmodel = "gpt-5"\n', + "utf-8" + ); + + const { removed } = await removeTomlServer(path, "context7"); + const content = await readFile(path, "utf-8"); + + expect(removed).toBe(true); + expect(content).toContain("[mcp_servers.other]"); + expect(content).toContain('url = "https://other.com"'); + expect(content).toContain("[mcp_servers.other.http_headers]"); + expect(content).toContain('X_API_KEY = "keep-me"'); + expect(content).toContain("[settings]"); + expect(content).not.toContain("[mcp_servers.context7]"); + expect(content).not.toContain("[mcp_servers.context7.http_headers]"); + }); + + test("removeTomlServer returns false when server is missing", async () => { + const path = join(tempDir, "config.toml"); + await writeFile(path, '[mcp_servers.other]\nurl = "https://other.com"\n', "utf-8"); + + const { removed } = await removeTomlServer(path, "context7"); + expect(removed).toBe(false); + }); +}); + +describe("AGENTS.md append", () => { + let tempDir: string; + + beforeEach(async () => { + tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`); + await mkdir(tempDir, { recursive: true }); + }); + + afterEach(async () => { + await rm(tempDir, { recursive: true, force: true }); + }); + + const marker = ""; + const ruleContent = "Use ctx7 CLI for docs.\n"; + + async function appendRule(filePath: string, existing?: string): Promise { + if (existing !== undefined) { + await writeFile(filePath, existing, "utf-8"); + } + + const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const section = `${marker}\n${ruleContent}${marker}`; + + let content = ""; + try { + content = await readFile(filePath, "utf-8"); + } catch {} + + if (content.includes(marker)) { + const regex = new RegExp(`${escapedMarker}\\n[\\s\\S]*?${escapedMarker}`); + await writeFile(filePath, content.replace(regex, section), "utf-8"); + } else { + const separator = + content.length > 0 && !content.endsWith("\n") ? "\n\n" : content.length > 0 ? "\n" : ""; + await mkdir(join(filePath, ".."), { recursive: true }); + await writeFile(filePath, content + separator + section + "\n", "utf-8"); + } + + return readFile(filePath, "utf-8"); + } + + test("creates new file cleanly", async () => { + const result = await appendRule(join(tempDir, "AGENTS.md")); + expect(result).toBe(`${marker}\n${ruleContent}${marker}\n`); + expect(result[0]).not.toBe("\n"); + }); + + test("appends to existing content with proper spacing", async () => { + const withNewline = await appendRule(join(tempDir, "a.md"), "# Rules\n"); + expect(withNewline).toContain("# Rules\n\n"); + + const withoutNewline = await appendRule(join(tempDir, "b.md"), "No trailing newline"); + expect(withoutNewline).toContain("No trailing newline\n\n"); + }); + + test("is idempotent on re-run", async () => { + const filePath = join(tempDir, "AGENTS.md"); + const first = await appendRule(filePath); + const second = await appendRule(filePath); + expect(second).toBe(first); + expect(second.match(//g)?.length).toBe(2); + }); + + test("replaces section without affecting surrounding content", async () => { + const filePath = join(tempDir, "AGENTS.md"); + await writeFile(filePath, `# Before\n\n${marker}\nold content\n${marker}\n\n# After\n`); + + const result = await appendRule(filePath); + expect(result).toContain("# Before"); + expect(result).toContain("# After"); + expect(result).not.toContain("old content"); + expect(result).toContain(ruleContent); + }); +}); + +describe("agent config integration", () => { + let tempDir: string; + + beforeEach(async () => { + tempDir = join(tmpdir(), `ctx7-agent-cfg-${Date.now()}`); + await mkdir(tempDir, { recursive: true }); + }); + + afterEach(async () => { + await rm(tempDir, { recursive: true, force: true }); + }); + + const apiKeyAuth: AuthOptions = { mode: "api-key", apiKey: "sk-test-123" }; + const oauthAuth: AuthOptions = { mode: "oauth" }; + + describe("claude", () => { + const agent = getAgent("claude"); + + test("buildEntry with api-key produces correct shape", () => { + const entry = agent.mcp.buildEntry(apiKeyAuth, "http"); + expect(entry).toEqual({ + type: "http", + url: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + }); + + test("buildEntry with oauth produces correct shape", () => { + const entry = agent.mcp.buildEntry(oauthAuth, "http"); + expect(entry).toEqual({ + type: "http", + url: "https://mcp.context7.com/mcp/oauth", + }); + }); + + test("uses CLAUDE_CONFIG_DIR for global Claude config, rules, skills, and detection", () => { + const previous = process.env.CLAUDE_CONFIG_DIR; + const customDir = join(tempDir, "xdg", "claude"); + process.env.CLAUDE_CONFIG_DIR = customDir; + try { + expect(agent.mcp.globalPaths).toEqual([join(customDir, ".claude.json")]); + expect(agent.rule.kind).toBe("file"); + if (agent.rule.kind === "file") { + expect(agent.rule.dir("global")).toBe(join(customDir, "rules")); + } + expect(agent.skill.dir("global")).toBe(join(customDir, "skills")); + expect(agent.detect.globalPaths).toEqual([customDir]); + } finally { + if (previous === undefined) { + delete process.env.CLAUDE_CONFIG_DIR; + } else { + process.env.CLAUDE_CONFIG_DIR = previous; + } + } + }); + + test("merges into JSON config with configKey mcpServers", async () => { + const path = join(tempDir, ".claude.json"); + const existing = await readJsonConfig(path); + const { config } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + agent.mcp.buildEntry(apiKeyAuth, "http") + ); + await writeJsonConfig(path, config); + + const result = await readJsonConfig(path); + const servers = result.mcpServers as Record; + expect(servers.context7).toEqual({ + type: "http", + url: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + }); + + test("overwrites existing config in JSON", async () => { + const path = join(tempDir, ".claude.json"); + await writeJsonConfig(path, { + mcpServers: { context7: { type: "http", url: "https://old.com" } }, + }); + + const existing = await readJsonConfig(path); + const { config, alreadyExists } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + agent.mcp.buildEntry(apiKeyAuth, "http") + ); + expect(alreadyExists).toBe(true); + await writeJsonConfig(path, config); + + const result = await readJsonConfig(path); + expect((result.mcpServers as Record).context7).toEqual({ + type: "http", + url: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + }); + }); + + describe("cursor", () => { + const agent = getAgent("cursor"); + + test("buildEntry with api-key produces correct shape (no type field)", () => { + const entry = agent.mcp.buildEntry(apiKeyAuth, "http"); + expect(entry).toEqual({ + url: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + expect(entry).not.toHaveProperty("type"); + }); + + test("buildEntry with oauth produces correct shape", () => { + const entry = agent.mcp.buildEntry(oauthAuth, "http"); + expect(entry).toEqual({ + url: "https://mcp.context7.com/mcp/oauth", + }); + }); + + test("merges into JSON config with configKey mcpServers", async () => { + const path = join(tempDir, "mcp.json"); + const existing = await readJsonConfig(path); + const { config } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + agent.mcp.buildEntry(oauthAuth, "http") + ); + await writeJsonConfig(path, config); + + const result = await readJsonConfig(path); + expect((result.mcpServers as Record).context7).toEqual({ + url: "https://mcp.context7.com/mcp/oauth", + }); + }); + + test("overwrites existing config in JSON", async () => { + const path = join(tempDir, "mcp.json"); + await writeJsonConfig(path, { + mcpServers: { context7: { url: "https://old.com" }, other: { url: "https://other.com" } }, + }); + + const existing = await readJsonConfig(path); + const { config, alreadyExists } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + agent.mcp.buildEntry(apiKeyAuth, "http") + ); + expect(alreadyExists).toBe(true); + await writeJsonConfig(path, config); + + const result = await readJsonConfig(path); + const servers = result.mcpServers as Record; + expect(servers.context7).toEqual({ + url: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + expect(servers.other).toEqual({ url: "https://other.com" }); + }); + }); + + describe("opencode", () => { + const agent = getAgent("opencode"); + + test("buildEntry with api-key includes type, url, enabled, and headers", () => { + const entry = agent.mcp.buildEntry(apiKeyAuth, "http"); + expect(entry).toEqual({ + type: "remote", + url: "https://mcp.context7.com/mcp", + enabled: true, + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + }); + + test("buildEntry with oauth includes type, url, enabled without headers", () => { + const entry = agent.mcp.buildEntry(oauthAuth, "http"); + expect(entry).toEqual({ + type: "remote", + url: "https://mcp.context7.com/mcp/oauth", + enabled: true, + }); + }); + + test("uses configKey 'mcp' instead of 'mcpServers'", () => { + expect(agent.mcp.configKey).toBe("mcp"); + }); + + test("merges into JSON config with configKey mcp", async () => { + const path = join(tempDir, "opencode.json"); + await writeJsonConfig(path, { $schema: "https://opencode.ai/config.json" }); + + const existing = await readJsonConfig(path); + const { config } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + agent.mcp.buildEntry(apiKeyAuth, "http") + ); + await writeJsonConfig(path, config); + + const result = await readJsonConfig(path); + expect(result.$schema).toBe("https://opencode.ai/config.json"); + expect((result.mcp as Record).context7).toEqual({ + type: "remote", + url: "https://mcp.context7.com/mcp", + enabled: true, + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + }); + + test("overwrites existing config in JSON", async () => { + const path = join(tempDir, "opencode.json"); + await writeJsonConfig(path, { + mcp: { context7: { type: "remote", url: "https://old.com", enabled: true } }, + }); + + const existing = await readJsonConfig(path); + const { config, alreadyExists } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + agent.mcp.buildEntry(oauthAuth, "http") + ); + expect(alreadyExists).toBe(true); + await writeJsonConfig(path, config); + + const result = await readJsonConfig(path); + expect((result.mcp as Record).context7).toEqual({ + type: "remote", + url: "https://mcp.context7.com/mcp/oauth", + enabled: true, + }); + }); + + test("works with JSONC files containing comments", async () => { + const path = join(tempDir, "opencode.jsonc"); + await writeFile( + path, + `{ + // OpenCode config + "$schema": "https://opencode.ai/config.json", + "mcp": {} +}`, + "utf-8" + ); + + const existing = await readJsonConfig(path); + const { config } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + agent.mcp.buildEntry(apiKeyAuth, "http") + ); + await writeJsonConfig(path, config); + + const result = await readJsonConfig(path); + expect(result.$schema).toBe("https://opencode.ai/config.json"); + expect((result.mcp as Record).context7).toBeTruthy(); + }); + }); + + describe("codex", () => { + const agent = getAgent("codex"); + + test("buildEntry with api-key produces correct shape", () => { + const entry = agent.mcp.buildEntry(apiKeyAuth, "http"); + expect(entry).toEqual({ + type: "http", + url: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + }); + + test("buildEntry with oauth produces correct shape", () => { + const entry = agent.mcp.buildEntry(oauthAuth, "http"); + expect(entry).toEqual({ + type: "http", + url: "https://mcp.context7.com/mcp/oauth", + }); + }); + + test("appends to TOML config", async () => { + const path = join(tempDir, "config.toml"); + const { alreadyExists } = await appendTomlServer( + path, + "context7", + agent.mcp.buildEntry(apiKeyAuth, "http") + ); + expect(alreadyExists).toBe(false); + + const content = await readFile(path, "utf-8"); + expect(content).toContain("[mcp_servers.context7]"); + expect(content).toContain('type = "http"'); + expect(content).toContain('url = "https://mcp.context7.com/mcp"'); + expect(content).toContain("[mcp_servers.context7.http_headers]"); + expect(content).toContain('CONTEXT7_API_KEY = "sk-test-123"'); + }); + + test("appends oauth entry to TOML without headers", async () => { + const path = join(tempDir, "config.toml"); + await appendTomlServer(path, "context7", agent.mcp.buildEntry(oauthAuth, "http")); + + const content = await readFile(path, "utf-8"); + expect(content).toContain("[mcp_servers.context7]"); + expect(content).toContain('url = "https://mcp.context7.com/mcp/oauth"'); + expect(content).not.toContain("http_headers"); + }); + + test("overwrites existing TOML config", async () => { + const path = join(tempDir, "config.toml"); + await appendTomlServer(path, "context7", agent.mcp.buildEntry(oauthAuth, "http")); + const { alreadyExists } = await appendTomlServer( + path, + "context7", + agent.mcp.buildEntry(apiKeyAuth, "http") + ); + + expect(alreadyExists).toBe(true); + const content = await readFile(path, "utf-8"); + expect(content.match(/\[mcp_servers\.context7\]/g)?.length).toBe(1); + expect(content).toContain('url = "https://mcp.context7.com/mcp"'); + expect(content).not.toContain("mcp/oauth"); + expect(content).toContain('CONTEXT7_API_KEY = "sk-test-123"'); + }); + + test("overwrites TOML config preserving other servers", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + '[mcp_servers.other]\nurl = "https://other.com"\n\n[mcp_servers.context7]\ntype = "http"\nurl = "https://old.com"\n' + ); + await appendTomlServer(path, "context7", agent.mcp.buildEntry(apiKeyAuth, "http")); + + const content = await readFile(path, "utf-8"); + expect(content).toContain("[mcp_servers.other]"); + expect(content).toContain('url = "https://other.com"'); + expect(content).toContain('url = "https://mcp.context7.com/mcp"'); + expect(content).not.toContain("https://old.com"); + }); + }); + + describe("gemini", () => { + const agent = getAgent("gemini"); + + test("buildEntry with api-key uses httpUrl", () => { + const entry = agent.mcp.buildEntry(apiKeyAuth, "http"); + expect(entry).toEqual({ + httpUrl: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + expect(entry).not.toHaveProperty("url"); + }); + + test("buildEntry with oauth uses httpUrl without headers", () => { + const entry = agent.mcp.buildEntry(oauthAuth, "http"); + expect(entry).toEqual({ + httpUrl: "https://mcp.context7.com/mcp/oauth", + }); + }); + + test("uses configKey mcpServers", () => { + expect(agent.mcp.configKey).toBe("mcpServers"); + }); + + test("merges into settings.json with mcpServers key", async () => { + const path = join(tempDir, "settings.json"); + await writeJsonConfig(path, { theme: "dark" }); + + const existing = await readJsonConfig(path); + const { config } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + agent.mcp.buildEntry(apiKeyAuth, "http") + ); + await writeJsonConfig(path, config); + + const result = await readJsonConfig(path); + expect(result.theme).toBe("dark"); + expect((result.mcpServers as Record).context7).toEqual({ + httpUrl: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + }); + + test("overwrites existing config in JSON", async () => { + const path = join(tempDir, "settings.json"); + await writeJsonConfig(path, { + mcpServers: { context7: { httpUrl: "https://old.com" } }, + }); + + const existing = await readJsonConfig(path); + const { config, alreadyExists } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + agent.mcp.buildEntry(apiKeyAuth, "http") + ); + expect(alreadyExists).toBe(true); + await writeJsonConfig(path, config); + + const result = await readJsonConfig(path); + expect((result.mcpServers as Record).context7).toEqual({ + httpUrl: "https://mcp.context7.com/mcp", + headers: { CONTEXT7_API_KEY: "sk-test-123" }, + }); + }); + }); + + describe("all agents have consistent config", () => { + test("all agents are covered", () => { + expect(ALL_AGENT_NAMES).toEqual([ + "claude", + "cursor", + "opencode", + "codex", + "antigravity", + "gemini", + ]); + }); + + test.each(ALL_AGENT_NAMES)("%s buildEntry returns url for both auth modes", (name) => { + const agent = getAgent(name); + const apiEntry = agent.mcp.buildEntry(apiKeyAuth, "http"); + const oauthEntry = agent.mcp.buildEntry(oauthAuth, "http"); + + const urlKey = name === "gemini" ? "httpUrl" : name === "antigravity" ? "serverUrl" : "url"; + expect(apiEntry[urlKey]).toBe("https://mcp.context7.com/mcp"); + expect(oauthEntry[urlKey]).toBe("https://mcp.context7.com/mcp/oauth"); + }); + + test.each(ALL_AGENT_NAMES)("%s buildEntry includes headers only for api-key auth", (name) => { + const agent = getAgent(name); + const apiEntry = agent.mcp.buildEntry(apiKeyAuth, "http"); + const oauthEntry = agent.mcp.buildEntry(oauthAuth, "http"); + + expect(apiEntry.headers).toEqual({ CONTEXT7_API_KEY: "sk-test-123" }); + expect(oauthEntry).not.toHaveProperty("headers"); + }); + + test.each(ALL_AGENT_NAMES)("%s buildEntry without apiKey omits headers", (name) => { + const agent = getAgent(name); + const entry = agent.mcp.buildEntry({ mode: "api-key" }, "http"); + expect(entry).not.toHaveProperty("headers"); + }); + }); + + describe("stdio buildEntry", () => { + const apiKeyAuth: AuthOptions = { mode: "api-key", apiKey: "sk-test-stdio" }; + const oauthAuth: AuthOptions = { mode: "oauth" }; + + test("claude stdio entry uses npx command with --api-key in args", () => { + const entry = getAgent("claude").mcp.buildEntry(apiKeyAuth, "stdio"); + expect(entry).toEqual({ + command: "npx", + args: ["-y", "@upstash/context7-mcp", "--api-key", "sk-test-stdio"], + }); + }); + + test("cursor stdio entry uses npx command with --api-key in args", () => { + const entry = getAgent("cursor").mcp.buildEntry(apiKeyAuth, "stdio"); + expect(entry).toEqual({ + command: "npx", + args: ["-y", "@upstash/context7-mcp", "--api-key", "sk-test-stdio"], + }); + }); + + test("opencode stdio entry uses type:local with array command", () => { + const entry = getAgent("opencode").mcp.buildEntry(apiKeyAuth, "stdio"); + expect(entry).toEqual({ + type: "local", + command: ["npx", "-y", "@upstash/context7-mcp", "--api-key", "sk-test-stdio"], + enabled: true, + }); + }); + + test("codex stdio entry uses npx command with --api-key in args", () => { + const entry = getAgent("codex").mcp.buildEntry(apiKeyAuth, "stdio"); + expect(entry).toEqual({ + command: "npx", + args: ["-y", "@upstash/context7-mcp", "--api-key", "sk-test-stdio"], + }); + }); + + test("gemini stdio entry uses npx command with --api-key in args", () => { + const entry = getAgent("gemini").mcp.buildEntry(apiKeyAuth, "stdio"); + expect(entry).toEqual({ + command: "npx", + args: ["-y", "@upstash/context7-mcp", "--api-key", "sk-test-stdio"], + }); + }); + + test.each(ALL_AGENT_NAMES)("%s stdio entry omits --api-key for oauth mode", (name) => { + const entry = getAgent(name).mcp.buildEntry(oauthAuth, "stdio"); + const args = (entry.args ?? entry.command) as string[]; + expect(args).not.toContain("--api-key"); + expect(args).toContain("@upstash/context7-mcp"); + }); + + test("codex stdio entry serializes to TOML correctly", () => { + const block = buildTomlServerBlock( + "context7", + getAgent("codex").mcp.buildEntry(apiKeyAuth, "stdio") + ); + expect(block).toContain("[mcp_servers.context7]"); + expect(block).toContain('command = "npx"'); + expect(block).toContain('args = ["-y","@upstash/context7-mcp","--api-key","sk-test-stdio"]'); + expect(block).not.toContain("http_headers"); + }); + }); + + describe("isStdioContext7Entry", () => { + test("detects standard command/args stdio entry", () => { + expect( + isStdioContext7Entry({ + command: "npx", + args: ["-y", "@upstash/context7-mcp", "--api-key", "k"], + }) + ).toBe(true); + }); + + test("detects entry with @latest specifier", () => { + expect( + isStdioContext7Entry({ command: "npx", args: ["-y", "@upstash/context7-mcp@latest"] }) + ).toBe(true); + }); + + test("detects entry with pinned version", () => { + expect( + isStdioContext7Entry({ command: "npx", args: ["-y", "@upstash/context7-mcp@2.0.0"] }) + ).toBe(true); + }); + + test("detects OpenCode array-command form", () => { + expect( + isStdioContext7Entry({ + type: "local", + command: ["npx", "-y", "@upstash/context7-mcp@latest"], + enabled: true, + }) + ).toBe(true); + }); + + test("returns false for HTTP entry", () => { + expect(isStdioContext7Entry({ url: "https://mcp.context7.com/mcp" })).toBe(false); + }); + + test("returns false for unrelated stdio package", () => { + expect(isStdioContext7Entry({ command: "npx", args: ["-y", "@some-other/package"] })).toBe( + false + ); + }); + + test("returns false for null/undefined", () => { + expect(isStdioContext7Entry(null)).toBe(false); + expect(isStdioContext7Entry(undefined)).toBe(false); + }); + }); + + describe("patchStdioApiKey", () => { + test("preserves @latest package specifier", () => { + const patched = patchStdioApiKey( + { command: "npx", args: ["-y", "@upstash/context7-mcp@latest"] }, + "new-key" + ); + expect(patched).toEqual({ + command: "npx", + args: ["-y", "@upstash/context7-mcp@latest", "--api-key", "new-key"], + }); + }); + + test("preserves pinned version specifier", () => { + const patched = patchStdioApiKey( + { command: "npx", args: ["-y", "@upstash/context7-mcp@2.0.0"] }, + "new-key" + ); + expect(patched.args).toEqual(["-y", "@upstash/context7-mcp@2.0.0", "--api-key", "new-key"]); + }); + + test("replaces an existing --api-key value", () => { + const patched = patchStdioApiKey( + { + command: "npx", + args: ["-y", "@upstash/context7-mcp@latest", "--api-key", "OLD"], + }, + "NEW" + ); + expect(patched.args).toEqual(["-y", "@upstash/context7-mcp@latest", "--api-key", "NEW"]); + }); + + test("removes --api-key when new key is undefined (oauth)", () => { + const patched = patchStdioApiKey( + { command: "npx", args: ["-y", "@upstash/context7-mcp", "--api-key", "OLD"] }, + undefined + ); + expect(patched.args).toEqual(["-y", "@upstash/context7-mcp"]); + }); + + test("preserves other args (e.g. --debug) untouched", () => { + const patched = patchStdioApiKey( + { + command: "npx", + args: ["-y", "@upstash/context7-mcp", "--debug", "--api-key", "OLD"], + }, + "NEW" + ); + expect(patched.args).toEqual(["-y", "@upstash/context7-mcp", "--debug", "--api-key", "NEW"]); + }); + + test("patches OpenCode array-command form", () => { + const patched = patchStdioApiKey( + { + type: "local", + command: ["npx", "-y", "@upstash/context7-mcp@latest", "--api-key", "OLD"], + enabled: true, + }, + "NEW" + ); + expect(patched).toEqual({ + type: "local", + command: ["npx", "-y", "@upstash/context7-mcp@latest", "--api-key", "NEW"], + enabled: true, + }); + }); + + test("preserves unrelated top-level fields", () => { + const patched = patchStdioApiKey( + { command: "npx", args: ["-y", "@upstash/context7-mcp"], cwd: "/custom" }, + "NEW" + ); + expect(patched.cwd).toBe("/custom"); + }); + }); + + describe("readTomlServerEntry", () => { + let tempDir: string; + + beforeEach(async () => { + tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`); + await mkdir(tempDir, { recursive: true }); + }); + + afterEach(async () => { + await rm(tempDir, { recursive: true, force: true }); + }); + + test("returns undefined for missing file", async () => { + expect(await readTomlServerEntry(join(tempDir, "nope.toml"), "context7")).toBeUndefined(); + }); + + test("returns undefined for missing section", async () => { + const path = join(tempDir, "config.toml"); + await writeFile(path, '[mcp_servers.other]\nurl = "https://other.com"\n', "utf-8"); + expect(await readTomlServerEntry(path, "context7")).toBeUndefined(); + }); + + test("parses string and array values from a stdio block", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + '[mcp_servers.context7]\ncommand = "npx"\nargs = ["-y", "@upstash/context7-mcp@latest", "--api-key", "OLD"]\n', + "utf-8" + ); + const entry = await readTomlServerEntry(path, "context7"); + expect(entry).toEqual({ + command: "npx", + args: ["-y", "@upstash/context7-mcp@latest", "--api-key", "OLD"], + }); + }); + + test("ignores http_headers sub-table", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + '[mcp_servers.context7]\ntype = "http"\nurl = "https://mcp.context7.com/mcp"\n\n[mcp_servers.context7.http_headers]\nCONTEXT7_API_KEY = "k"\n', + "utf-8" + ); + const entry = await readTomlServerEntry(path, "context7"); + expect(entry).toEqual({ type: "http", url: "https://mcp.context7.com/mcp" }); + }); + + test("round-trips through patchStdioApiKey + appendTomlServer", async () => { + const path = join(tempDir, "config.toml"); + await writeFile( + path, + '[mcp_servers.context7]\ncommand = "npx"\nargs = ["-y", "@upstash/context7-mcp@latest", "--api-key", "OLD"]\n', + "utf-8" + ); + const existing = await readTomlServerEntry(path, "context7"); + expect(existing).toBeDefined(); + expect(isStdioContext7Entry(existing)).toBe(true); + const patched = patchStdioApiKey(existing!, "NEW"); + await appendTomlServer(path, "context7", patched); + const content = await readFile(path, "utf-8"); + expect(content).toContain("@upstash/context7-mcp@latest"); + expect(content).toContain('"--api-key","NEW"'); + expect(content).not.toContain('"OLD"'); + }); + }); +}); diff --git a/packages/cli/src/__tests__/skill-list.test.ts b/packages/cli/src/__tests__/skill-list.test.ts new file mode 100644 index 0000000..c622141 --- /dev/null +++ b/packages/cli/src/__tests__/skill-list.test.ts @@ -0,0 +1,75 @@ +import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"; +import { Command } from "commander"; +import { mkdir, rm, realpath } from "fs/promises"; +import { join } from "path"; +import { tmpdir } from "os"; + +const trackEvent = vi.fn(); +let logOutput: string[]; + +vi.mock("../utils/tracking.js", () => ({ + trackEvent: (...args: unknown[]) => trackEvent(...args), +})); + +import { registerSkillCommands } from "../commands/skill.js"; + +let tempDir: string; +let originalCwd: string; + +async function runCommand(...args: string[]): Promise { + const program = new Command(); + program.exitOverride(); + registerSkillCommands(program); + await program.parseAsync(["node", "test", ...args]); +} + +beforeEach(async () => { + vi.clearAllMocks(); + logOutput = []; + vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => { + logOutput.push(args.join(" ")); + }); + vi.spyOn(console, "error").mockImplementation(() => {}); + originalCwd = process.cwd(); + const rawTempDir = join(tmpdir(), `ctx7-skills-list-${Date.now()}`); + await mkdir(rawTempDir, { recursive: true }); + tempDir = await realpath(rawTempDir); + process.chdir(tempDir); +}); + +afterEach(async () => { + process.chdir(originalCwd); + await rm(tempDir, { recursive: true, force: true }); + vi.restoreAllMocks(); +}); + +describe("skills list command", () => { + test("outputs installed skills as JSON", async () => { + await mkdir(join(tempDir, ".agents", "skills", "find-docs"), { recursive: true }); + await mkdir(join(tempDir, ".cursor", "skills", "cursor-helper"), { recursive: true }); + + await runCommand("skills", "list", "--json"); + + expect(JSON.parse(logOutput.join("\n"))).toEqual({ + skills: [ + { + name: "find-docs", + path: join(tempDir, ".agents", "skills", "find-docs"), + source: "universal", + }, + { + name: "cursor-helper", + path: join(tempDir, ".cursor", "skills", "cursor-helper"), + source: "cursor", + }, + ], + }); + expect(trackEvent).toHaveBeenCalledWith("command", { name: "list" }); + }); + + test("outputs an empty JSON list when no skills are installed", async () => { + await runCommand("skills", "list", "--json"); + + expect(JSON.parse(logOutput.join("\n"))).toEqual({ skills: [] }); + }); +}); diff --git a/packages/cli/src/__tests__/storage-paths.test.ts b/packages/cli/src/__tests__/storage-paths.test.ts new file mode 100644 index 0000000..0593367 --- /dev/null +++ b/packages/cli/src/__tests__/storage-paths.test.ts @@ -0,0 +1,70 @@ +import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"; +import { join } from "path"; + +import { + getCacheDir, + getConfigDir, + getCredentialsFilePath, + getPreviewsDir, + getStateDir, + getUpdateStateFilePath, +} from "../utils/storage-paths.js"; + +const HOME = "/fake-home"; + +beforeEach(() => { + // os.homedir() reads $HOME first on POSIX, so stubbing the env var pins the + // home directory deterministically without mocking the `os` builtin (which + // resolves unreliably across Node versions / worker pooling in CI). + vi.stubEnv("HOME", HOME); + vi.stubEnv("XDG_CONFIG_HOME", undefined); + vi.stubEnv("XDG_STATE_HOME", undefined); + vi.stubEnv("XDG_CACHE_HOME", undefined); +}); + +afterEach(() => { + vi.unstubAllEnvs(); + vi.restoreAllMocks(); +}); + +describe("XDG defaults", () => { + test("config dir defaults to ~/.config/context7", () => { + expect(getConfigDir()).toBe(join(HOME, ".config", "context7")); + expect(getCredentialsFilePath()).toBe(join(HOME, ".config", "context7", "credentials.json")); + }); + + test("state dir defaults to ~/.local/state/context7", () => { + expect(getStateDir()).toBe(join(HOME, ".local", "state", "context7")); + expect(getUpdateStateFilePath()).toBe( + join(HOME, ".local", "state", "context7", "cli-state.json") + ); + }); + + test("cache dir defaults to ~/.cache/context7 and previews live under it", () => { + expect(getCacheDir()).toBe(join(HOME, ".cache", "context7")); + expect(getPreviewsDir()).toBe(join(HOME, ".cache", "context7", "previews")); + }); +}); + +describe("XDG overrides", () => { + test("honors XDG_CONFIG_HOME, XDG_STATE_HOME, and XDG_CACHE_HOME", () => { + vi.stubEnv("XDG_CONFIG_HOME", "/cfg"); + vi.stubEnv("XDG_STATE_HOME", "/state"); + vi.stubEnv("XDG_CACHE_HOME", "/cache"); + + expect(getConfigDir()).toBe(join("/cfg", "context7")); + expect(getStateDir()).toBe(join("/state", "context7")); + expect(getCacheDir()).toBe(join("/cache", "context7")); + expect(getPreviewsDir()).toBe(join("/cache", "context7", "previews")); + }); + + test("ignores empty XDG values and uses the default", () => { + vi.stubEnv("XDG_CONFIG_HOME", ""); + expect(getConfigDir()).toBe(join(HOME, ".config", "context7")); + }); + + test("ignores relative XDG values per the spec and uses the default", () => { + vi.stubEnv("XDG_STATE_HOME", "relative/path"); + expect(getStateDir()).toBe(join(HOME, ".local", "state", "context7")); + }); +}); diff --git a/packages/cli/src/__tests__/update-check.test.ts b/packages/cli/src/__tests__/update-check.test.ts new file mode 100644 index 0000000..cc615d4 --- /dev/null +++ b/packages/cli/src/__tests__/update-check.test.ts @@ -0,0 +1,301 @@ +import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"; +import { mkdir, readFile, rm, writeFile } from "fs/promises"; +import { join } from "path"; +import { tmpdir } from "os"; + +import { + checkForUpdates, + compareVersions, + detectInstallMethod, + getUpgradePlan, + markUpdateNotificationShown, + shouldShowUpdateNotification, + shouldSkipUpdateNotifier, +} from "../utils/update-check.js"; + +let tempDir: string; +let stateFile: string; + +beforeEach(async () => { + tempDir = join(tmpdir(), `ctx7-update-${Date.now()}`); + stateFile = join(tempDir, "cli-state.json"); + await mkdir(tempDir, { recursive: true }); + vi.stubGlobal( + "fetch", + vi.fn(() => { + throw new Error("fetch not mocked"); + }) + ); +}); + +afterEach(async () => { + await rm(tempDir, { recursive: true, force: true }); + vi.unstubAllGlobals(); + vi.unstubAllEnvs(); + vi.doUnmock("os"); + vi.resetModules(); + vi.restoreAllMocks(); +}); + +describe("compareVersions", () => { + test("orders semantic versions correctly", () => { + expect(compareVersions("0.3.14", "0.3.13")).toBeGreaterThan(0); + expect(compareVersions("0.3.13", "0.3.13")).toBe(0); + expect(compareVersions("0.3.13", "0.3.14")).toBeLessThan(0); + }); +}); + +describe("detectInstallMethod", () => { + test("detects npx and pnpm dlx", () => { + expect( + detectInstallMethod({ + npm_execpath: "/usr/local/lib/node_modules/npm/bin/npm-cli.js", + npm_command: "exec", + }) + ).toBe("npx"); + + expect( + detectInstallMethod({ + npm_execpath: "/Users/test/Library/pnpm/pnpm.cjs", + npm_command: "dlx", + }) + ).toBe("pnpm-dlx"); + }); + + test("detects npm, pnpm, bun, and bunx style shells", () => { + expect( + detectInstallMethod({ + npm_execpath: "/usr/local/lib/node_modules/npm/bin/npm-cli.js", + npm_command: "install", + }) + ).toBe("npm-global"); + + expect( + detectInstallMethod({ + npm_execpath: "/Users/test/Library/pnpm/pnpm.cjs", + npm_command: "add", + }) + ).toBe("pnpm-global"); + + expect( + detectInstallMethod({ + npm_execpath: "/Users/test/.bun/bin/bun", + npm_command: "add", + }) + ).toBe("bun-global"); + + expect( + detectInstallMethod({ + npm_execpath: "/Users/test/.bun/bin/bun", + npm_command: "x", + }) + ).toBe("bunx"); + }); + + test("falls back to npm-global for npm user agents", () => { + expect(detectInstallMethod({ npm_config_user_agent: "npm/10.0.0 node/v22.0.0" })).toBe( + "npm-global" + ); + }); +}); + +describe("getUpgradePlan", () => { + test("returns explicit runner commands for ephemeral installs", () => { + expect(getUpgradePlan("npx").displayCommand).toBe("npx ctx7@latest "); + expect(getUpgradePlan("pnpm-dlx").displayCommand).toBe("pnpm dlx ctx7@latest "); + }); + + test("does not auto-run upgrade plans for unknown installs", () => { + expect(getUpgradePlan("unknown").canRun).toBe(false); + }); +}); + +describe("checkForUpdates", () => { + test("fetches and caches the latest version", async () => { + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ version: "9.9.9" }), + }) + ); + + const info = await checkForUpdates({ + force: true, + stateFile, + now: 123456, + }); + + expect(info?.latestVersion).toBe("9.9.9"); + expect(info?.updateAvailable).toBe(true); + }); + + test("uses cached latest version when the cache is fresh", async () => { + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ version: "9.9.9" }), + }) + ); + + await checkForUpdates({ force: true, stateFile, now: 1000 }); + + const fetchMock = vi.mocked(fetch); + fetchMock.mockClear(); + + const info = await checkForUpdates({ + stateFile, + now: 2000, + cacheTtlMs: 10_000, + }); + + expect(info?.latestVersion).toBe("9.9.9"); + expect(fetchMock).not.toHaveBeenCalled(); + }); +}); + +describe("default cli-state persistence", () => { + test("writes updater state under the XDG state directory when using the default path", async () => { + const fakeHome = join(tempDir, "fake-home"); + await mkdir(fakeHome, { recursive: true }); + + vi.resetModules(); + vi.doMock("os", async () => { + const actual = await vi.importActual("os"); + return { ...actual, homedir: () => fakeHome }; + }); + + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ version: "9.9.9" }), + }) + ); + + const updateCheck = await import("../utils/update-check.js"); + + await updateCheck.checkForUpdates({ force: true, now: 1000 }); + await updateCheck.markUpdateNotificationShown("9.9.9", { now: 2000 }); + + const persisted = JSON.parse( + await readFile(join(fakeHome, ".local", "state", "context7", "cli-state.json"), "utf-8") + ) as { + latestVersion?: string; + lastCheckedAt?: number; + notifiedVersion?: string; + lastNotifiedAt?: number; + }; + + expect(persisted).toEqual({ + latestVersion: "9.9.9", + lastCheckedAt: 1000, + notifiedVersion: "9.9.9", + lastNotifiedAt: 2000, + }); + }); + + test("honors XDG_STATE_HOME for updater state", async () => { + // Mock homedir so the legacy-migration step cannot touch the real ~/.context7. + const fakeHome = join(tempDir, "fake-home"); + await mkdir(fakeHome, { recursive: true }); + const stateHome = join(tempDir, "xdg-state"); + vi.stubEnv("XDG_STATE_HOME", stateHome); + + vi.resetModules(); + vi.doMock("os", async () => { + const actual = await vi.importActual("os"); + return { ...actual, homedir: () => fakeHome }; + }); + + vi.stubGlobal( + "fetch", + vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ version: "9.9.9" }), + }) + ); + + const updateCheck = await import("../utils/update-check.js"); + await updateCheck.checkForUpdates({ force: true, now: 1000 }); + + const persisted = JSON.parse( + await readFile(join(stateHome, "context7", "cli-state.json"), "utf-8") + ) as { + latestVersion?: string; + lastCheckedAt?: number; + }; + + expect(persisted).toEqual({ + latestVersion: "9.9.9", + lastCheckedAt: 1000, + }); + }); + + test("migrates legacy ~/.context7 cli-state into the XDG state directory", async () => { + const fakeHome = join(tempDir, "fake-home"); + const legacyDir = join(fakeHome, ".context7"); + await mkdir(legacyDir, { recursive: true }); + await writeFile( + join(legacyDir, "cli-state.json"), + JSON.stringify({ latestVersion: "9.9.9", lastCheckedAt: 1000 }), + "utf-8" + ); + + vi.resetModules(); + vi.doMock("os", async () => { + const actual = await vi.importActual("os"); + return { ...actual, homedir: () => fakeHome }; + }); + + vi.stubGlobal( + "fetch", + vi.fn(() => { + throw new Error("fetch should not be called for a fresh migrated cache"); + }) + ); + + const updateCheck = await import("../utils/update-check.js"); + + const info = await updateCheck.checkForUpdates({ + now: 2000, + cacheTtlMs: 10_000, + }); + + expect(info?.latestVersion).toBe("9.9.9"); + expect(fetch).not.toHaveBeenCalled(); + expect( + JSON.parse( + await readFile(join(fakeHome, ".local", "state", "context7", "cli-state.json"), "utf-8") + ) + ).toEqual({ latestVersion: "9.9.9", lastCheckedAt: 1000 }); + }); +}); + +describe("update notifications", () => { + test("respects notification cooldown per latest version", async () => { + const info = { + currentVersion: "0.3.13", + latestVersion: "9.9.9", + updateAvailable: true, + installMethod: "npm-global" as const, + upgradePlan: getUpgradePlan("npm-global"), + }; + + expect(await shouldShowUpdateNotification(info, { stateFile, now: 1000 })).toBe(true); + + await markUpdateNotificationShown("9.9.9", { stateFile, now: 1000 }); + + expect(await shouldShowUpdateNotification(info, { stateFile, now: 2000 })).toBe(false); + expect( + await shouldShowUpdateNotification(info, { stateFile, now: 1000 + 25 * 60 * 60 * 1000 }) + ).toBe(true); + }); + + test("skips notifier for json and version argv", () => { + expect(shouldSkipUpdateNotifier(["node", "ctx7", "library", "react", "--json"])).toBe(true); + expect(shouldSkipUpdateNotifier(["node", "ctx7", "--version"])).toBe(true); + expect(shouldSkipUpdateNotifier(["node", "ctx7", "skills", "list"])).toBe(false); + }); +}); diff --git a/packages/cli/src/__tests__/upgrade-command.test.ts b/packages/cli/src/__tests__/upgrade-command.test.ts new file mode 100644 index 0000000..62c17cc --- /dev/null +++ b/packages/cli/src/__tests__/upgrade-command.test.ts @@ -0,0 +1,319 @@ +import { beforeEach, describe, expect, test, vi } from "vitest"; +import { Command } from "commander"; + +const trackEvent = vi.fn(); +const checkForUpdates = vi.fn(); +const getUpgradePlan = vi.fn(); +const markUpdateNotificationShown = vi.fn(); +const shouldShowUpdateNotification = vi.fn(); +const shouldSkipUpdateNotifier = vi.fn(); +const confirm = vi.fn(); +const spawn = vi.fn(); + +vi.mock("../utils/tracking.js", () => ({ + trackEvent: (...args: unknown[]) => trackEvent(...args), +})); + +vi.mock("../utils/update-check.js", () => ({ + checkForUpdates: (...args: unknown[]) => checkForUpdates(...args), + getUpgradePlan: (...args: unknown[]) => getUpgradePlan(...args), + markUpdateNotificationShown: (...args: unknown[]) => markUpdateNotificationShown(...args), + shouldShowUpdateNotification: (...args: unknown[]) => shouldShowUpdateNotification(...args), + shouldSkipUpdateNotifier: (...args: unknown[]) => shouldSkipUpdateNotifier(...args), +})); + +vi.mock("@inquirer/prompts", () => ({ + confirm: (...args: unknown[]) => confirm(...args), +})); + +vi.mock("child_process", () => ({ + spawn: (...args: unknown[]) => spawn(...args), +})); + +import { maybeShowUpgradeNotice, registerUpgradeCommand } from "../commands/upgrade.js"; + +let logOutput: string[]; +const ANSI_PATTERN = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g; + +function stripAnsi(text: string): string { + return text.replace(ANSI_PATTERN, ""); +} + +async function runCommand(...args: string[]): Promise { + const program = new Command(); + program.exitOverride(); + registerUpgradeCommand(program); + await program.parseAsync(["node", "test", ...args]); +} + +beforeEach(() => { + vi.clearAllMocks(); + logOutput = []; + shouldShowUpdateNotification.mockResolvedValue(true); + shouldSkipUpdateNotifier.mockReturnValue(false); + vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => { + logOutput.push(args.join(" ")); + }); + spawn.mockReturnValue({ + on: (event: string, handler: (value?: number) => void) => { + if (event === "close") handler(0); + return undefined; + }, + }); +}); + +function plainLogOutput(): string[] { + return logOutput.map(stripAnsi); +} + +describe("upgrade command", () => { + test("reports when ctx7 is already up to date", async () => { + checkForUpdates.mockResolvedValue({ + currentVersion: "0.3.13", + latestVersion: "0.3.13", + updateAvailable: false, + installMethod: "npm-global", + upgradePlan: { + displayCommand: "npm install -g ctx7@latest", + }, + }); + + await runCommand("upgrade"); + + expect(plainLogOutput().some((line) => line.includes("ctx7 is up to date"))).toBe(true); + expect(trackEvent).toHaveBeenCalledWith("command", { name: "upgrade" }); + }); + + test("prints upgrade instructions in check mode", async () => { + checkForUpdates.mockResolvedValue({ + currentVersion: "0.3.13", + latestVersion: "0.3.99", + updateAvailable: true, + installMethod: "npm-global", + upgradePlan: { + displayCommand: "npm install -g ctx7@latest", + canRun: true, + needsExplicitVersion: false, + }, + }); + + await runCommand("upgrade", "--check"); + + expect(plainLogOutput().some((line) => line.includes("Update available"))).toBe(true); + expect(plainLogOutput().some((line) => line.includes("npm install -g ctx7@latest"))).toBe(true); + expect(spawn).not.toHaveBeenCalled(); + }); + + test("explains ephemeral runners instead of trying to self-upgrade", async () => { + checkForUpdates.mockResolvedValue({ + currentVersion: "0.3.13", + latestVersion: "0.3.99", + updateAvailable: true, + installMethod: "npx", + upgradePlan: { + displayCommand: "npx ctx7@latest ", + canRun: false, + needsExplicitVersion: true, + }, + }); + + await runCommand("upgrade"); + + expect(plainLogOutput().some((line) => line.includes("ephemeral runner"))).toBe(true); + expect(plainLogOutput().some((line) => line.includes("npx ctx7@latest "))).toBe(true); + expect(spawn).not.toHaveBeenCalled(); + }); + + test("runs the upgrade command with --yes when possible", async () => { + checkForUpdates.mockResolvedValue({ + currentVersion: "0.3.13", + latestVersion: "0.3.99", + updateAvailable: true, + installMethod: "npm-global", + upgradePlan: { + command: "npm", + args: ["install", "-g", "ctx7@latest"], + displayCommand: "npm install -g ctx7@latest", + canRun: true, + needsExplicitVersion: false, + }, + }); + + await runCommand("upgrade", "--yes"); + + expect(spawn).toHaveBeenCalledWith( + "npm", + ["install", "-g", "ctx7@latest"], + expect.objectContaining({ stdio: "inherit" }) + ); + }); + + test("falls back to getUpgradePlan when update check fails", async () => { + checkForUpdates.mockResolvedValue(null); + getUpgradePlan.mockReturnValue({ + displayCommand: "npm install -g ctx7@latest", + }); + + await runCommand("upgrade", "--check"); + + expect(plainLogOutput().some((line) => line.includes("Couldn't check for updates"))).toBe(true); + expect(plainLogOutput().some((line) => line.includes("npm install -g ctx7@latest"))).toBe(true); + }); + + test("shows retry guidance when the upgrade command fails", async () => { + spawn.mockReturnValue({ + on: (event: string, handler: (value?: number) => void) => { + if (event === "close") handler(243); + return undefined; + }, + }); + checkForUpdates.mockResolvedValue({ + currentVersion: "0.3.13", + latestVersion: "0.3.99", + updateAvailable: true, + installMethod: "npm-global", + upgradePlan: { + command: "npm", + args: ["install", "-g", "ctx7@latest"], + displayCommand: "npm install -g ctx7@latest", + canRun: true, + needsExplicitVersion: false, + installMethod: "npm-global", + }, + }); + + await runCommand("upgrade", "--yes"); + + expect( + plainLogOutput().some((line) => line.includes("Upgrade command exited with code 243")) + ).toBe(true); + expect(plainLogOutput().some((line) => line.includes("Try rerunning:"))).toBe(true); + expect(plainLogOutput().some((line) => line.includes("permissions"))).toBe(true); + }); + + test("shows permissions guidance when install method is unknown but command is global npm", async () => { + spawn.mockReturnValue({ + on: (event: string, handler: (value?: number) => void) => { + if (event === "close") handler(243); + return undefined; + }, + }); + checkForUpdates.mockResolvedValue({ + currentVersion: "0.3.13", + latestVersion: "0.3.99", + updateAvailable: true, + installMethod: "unknown", + upgradePlan: { + command: "npm", + args: ["install", "-g", "ctx7@latest"], + displayCommand: "npm install -g ctx7@latest", + canRun: false, + needsExplicitVersion: false, + installMethod: "unknown", + }, + }); + + await runCommand("upgrade", "--yes"); + + expect(spawn).not.toHaveBeenCalled(); + expect(plainLogOutput().some((line) => line.includes("Run npm install -g ctx7@latest"))).toBe( + true + ); + }); +}); + +describe("pre-command upgrade notice", () => { + test("shows a non-blocking notice for upgradeable installs", async () => { + checkForUpdates.mockResolvedValue({ + currentVersion: "0.3.11", + latestVersion: "0.3.13", + updateAvailable: true, + upgradePlan: { + command: "npm", + args: ["install", "-g", "ctx7@latest"], + displayCommand: "npm install -g ctx7@latest", + canRun: true, + needsExplicitVersion: false, + }, + }); + await maybeShowUpgradeNotice({ + actionName: "library", + argv: ["node", "ctx7", "library", "react"], + isInteractive: true, + }); + + expect(plainLogOutput().some((line) => line.includes("Update available:"))).toBe(true); + expect(plainLogOutput().some((line) => line.includes("Run ctx7 upgrade to update now"))).toBe( + true + ); + expect(plainLogOutput().some((line) => line.includes("npm install -g ctx7@latest"))).toBe(true); + expect(confirm).not.toHaveBeenCalled(); + expect(spawn).not.toHaveBeenCalled(); + expect(markUpdateNotificationShown).toHaveBeenCalledWith("0.3.13"); + }); + + test("shows guidance-only notice for unknown installs", async () => { + checkForUpdates.mockResolvedValue({ + currentVersion: "0.3.11", + latestVersion: "0.3.13", + updateAvailable: true, + upgradePlan: { + command: "npm", + args: ["install", "-g", "ctx7@latest"], + displayCommand: "npm install -g ctx7@latest", + canRun: false, + needsExplicitVersion: false, + }, + }); + + await maybeShowUpgradeNotice({ + actionName: "library", + argv: ["node", "ctx7", "library", "react"], + isInteractive: true, + }); + + expect( + plainLogOutput().some((line) => line.includes("Run ctx7 upgrade for update steps")) + ).toBe(true); + expect(plainLogOutput().some((line) => line.includes("npm install -g ctx7@latest"))).toBe(true); + expect(spawn).not.toHaveBeenCalled(); + expect(markUpdateNotificationShown).toHaveBeenCalledWith("0.3.13"); + }); + + test("shows runner-specific guidance for ephemeral installs", async () => { + checkForUpdates.mockResolvedValue({ + currentVersion: "0.3.11", + latestVersion: "0.3.13", + updateAvailable: true, + upgradePlan: { + displayCommand: "npx ctx7@latest ", + canRun: false, + needsExplicitVersion: true, + }, + }); + + await maybeShowUpgradeNotice({ + actionName: "library", + argv: ["node", "ctx7", "library", "react"], + isInteractive: true, + }); + + expect(plainLogOutput().some((line) => line.includes("Use npx ctx7@latest "))).toBe( + true + ); + expect(plainLogOutput().some((line) => line.includes("ctx7 upgrade"))).toBe(false); + expect(confirm).not.toHaveBeenCalled(); + expect(spawn).not.toHaveBeenCalled(); + expect(markUpdateNotificationShown).toHaveBeenCalledWith("0.3.13"); + }); + + test("skips notice for upgrade command", async () => { + await maybeShowUpgradeNotice({ + actionName: "upgrade", + argv: ["node", "ctx7", "upgrade"], + isInteractive: true, + }); + + expect(checkForUpdates).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/cli/src/commands/auth.ts b/packages/cli/src/commands/auth.ts new file mode 100644 index 0000000..df89310 --- /dev/null +++ b/packages/cli/src/commands/auth.ts @@ -0,0 +1,266 @@ +import { Command } from "commander"; +import pc from "picocolors"; +import ora from "ora"; +import open from "open"; +import boxen from "boxen"; +import { + saveTokens, + clearTokens, + getValidAccessToken, + startDeviceAuthorization, + pollDeviceToken, + DEFAULT_DEVICE_POLL_INTERVAL_SECONDS, +} from "../utils/auth.js"; + +import { trackEvent } from "../utils/tracking.js"; +import { CLI_CLIENT_ID } from "../constants.js"; +import { getBaseUrl } from "../utils/api.js"; + +let baseUrl = "https://context7.com"; + +export function setAuthBaseUrl(url: string): void { + baseUrl = url; +} + +export function registerAuthCommands(program: Command): void { + program + .command("login") + .description("Log in to Context7") + .option("--no-browser", "Don't open browser automatically") + .action(async (options) => { + await loginCommand(options); + }); + + program + .command("logout") + .description("Log out of Context7") + .action(() => { + logoutCommand(); + }); + + program + .command("whoami") + .description("Show current login status") + .action(async () => { + await whoamiCommand(); + }); +} + +function renderDeviceCodeBox( + userCode: string, + verificationUri: string, + verificationUriComplete: string | undefined +): string { + const codeLine = `${pc.dim("Your one-time code:")}\n\n ${pc.green(pc.bold(userCode))}`; + // Per RFC 8628 §3.3, even when verification_uri_complete is available we + // still show the bare verification_uri so users on screen readers / paper + // can type it manually. + const linkLine = verificationUriComplete + ? `${pc.dim("Open this link to approve:")}\n${pc.cyan(verificationUriComplete)}\n\n${pc.dim("Or visit")} ${pc.cyan(verificationUri)} ${pc.dim("and enter the code above.")}` + : `${pc.dim("Visit:")} ${pc.cyan(verificationUri)}`; + return boxen(`${codeLine}\n\n${linkLine}`, { + title: "Sign in to Context7", + titleAlignment: "left", + padding: 1, + margin: { top: 1, bottom: 1, left: 2, right: 2 }, + borderStyle: "round", + borderColor: "gray", + }); +} + +/** Prints a prompt and resolves on the next keypress. No-op when stdin isn't a TTY. */ +function waitForEnter(prompt: string): Promise { + if (!process.stdin.isTTY) return Promise.resolve(); + return new Promise((resolve) => { + process.stdout.write(` ${pc.dim(prompt)} `); + const onData = (chunk: Buffer) => { + // Ctrl-C + if (chunk[0] === 0x03) { + process.stdin.removeListener("data", onData); + process.stdin.setRawMode?.(false); + process.stdin.pause(); + process.stdout.write("\n"); + process.exit(130); + } + process.stdin.removeListener("data", onData); + process.stdin.setRawMode?.(false); + process.stdin.pause(); + process.stdout.write("\n"); + resolve(); + }; + process.stdin.setRawMode?.(true); + process.stdin.resume(); + process.stdin.on("data", onData); + }); +} + +async function announceIdentity(accessToken: string): Promise { + try { + const whoami = await fetchWhoami(accessToken); + const name = whoami.email || whoami.name; + if (!name) return "Login successful!"; + const team = whoami.teamspace?.name; + return team + ? `Logged in as ${pc.bold(name)} ${pc.dim(`(${team})`)}` + : `Logged in as ${pc.bold(name)}`; + } catch { + return "Login successful!"; + } +} + +export async function performLogin(openBrowser = true): Promise { + const spinner = ora("Preparing login...").start(); + + let authorization; + try { + authorization = await startDeviceAuthorization(baseUrl, CLI_CLIENT_ID); + } catch (error) { + spinner.fail(pc.red("Login failed")); + if (error instanceof Error) console.error(pc.red(error.message)); + return null; + } + + spinner.stop(); + + console.log( + renderDeviceCodeBox( + authorization.user_code, + authorization.verification_uri, + authorization.verification_uri_complete + ) + ); + + const target = authorization.verification_uri_complete ?? authorization.verification_uri; + if (openBrowser) { + await waitForEnter("Press Enter to open the browser, or Ctrl-C to quit..."); + try { + await open(target); + } catch { + console.log(pc.dim(` Couldn't open a browser — visit the link above manually.`)); + } + } else { + console.log(pc.dim(" Open the link above in any browser to continue.")); + console.log(""); + } + + const waitingSpinner = ora({ text: "Waiting for authorization...", indent: 2 }).start(); + + const deadline = Date.now() + authorization.expires_in * 1000; + let intervalMs = (authorization.interval ?? DEFAULT_DEVICE_POLL_INTERVAL_SECONDS) * 1000; + + while (Date.now() < deadline) { + await new Promise((resolve) => setTimeout(resolve, intervalMs)); + try { + const result = await pollDeviceToken(baseUrl, CLI_CLIENT_ID, authorization.device_code); + if (result.status === "approved" && result.tokens) { + saveTokens(result.tokens); + const successText = await announceIdentity(result.tokens.access_token); + waitingSpinner.succeed(pc.green(successText)); + return result.tokens.access_token; + } + if (result.status === "slow_down") { + intervalMs += 5000; + continue; + } + if (result.status === "denied") { + waitingSpinner.fail(pc.red("Authorization denied.")); + return null; + } + if (result.status === "expired") { + waitingSpinner.fail(pc.red("Code expired. Run login again.")); + return null; + } + if (result.status === "transient") { + // RFC 8628 §3.5: client MUST unilaterally reduce polling frequency on + // connection timeout. Apply +5s like slow_down so a flaky network or + // 5xx burst doesn't keep hitting at the original cadence. + intervalMs += 5000; + continue; + } + // pending — keep polling at the current cadence. + } catch (error) { + waitingSpinner.fail(pc.red("Login failed")); + if (error instanceof Error) console.error(pc.red(error.message)); + return null; + } + } + + waitingSpinner.fail(pc.red("Code expired without approval.")); + return null; +} + +async function loginCommand(options: { browser: boolean }): Promise { + trackEvent("command", { name: "login" }); + const existingToken = await getValidAccessToken(); + if (existingToken) { + console.log(pc.yellow("You are already logged in.")); + console.log(pc.dim("Run 'ctx7 logout' first if you want to log in with a different account.")); + return; + } + clearTokens(); + + const token = await performLogin(options.browser); + if (!token) { + process.exit(1); + } + console.log(""); + console.log(pc.dim("You can now use authenticated Context7 features.")); +} + +function logoutCommand(): void { + trackEvent("command", { name: "logout" }); + if (clearTokens()) { + console.log(pc.green("Logged out successfully.")); + } else { + console.log(pc.yellow("You are not logged in.")); + } +} + +async function whoamiCommand(): Promise { + trackEvent("command", { name: "whoami" }); + const accessToken = await getValidAccessToken(); + + if (!accessToken) { + console.log(pc.yellow("Not logged in.")); + console.log(pc.dim("Run 'ctx7 login' to authenticate.")); + return; + } + + console.log(pc.green("Logged in")); + + try { + const whoami = await fetchWhoami(accessToken); + if (whoami.name) { + console.log(`${pc.dim("Name:".padEnd(13))}${whoami.name}`); + } + if (whoami.email) { + console.log(`${pc.dim("Email:".padEnd(13))}${whoami.email}`); + } + if (whoami.teamspace) { + console.log(`${pc.dim("Teamspace:".padEnd(13))}${whoami.teamspace.name}`); + } + } catch { + console.log(pc.dim("(Session may be expired - run 'ctx7 login' to refresh)")); + } +} + +interface WhoamiResponse { + success: boolean; + name: string | null; + email: string | null; + teamspace: { id: string; name: string } | null; +} + +async function fetchWhoami(accessToken: string): Promise { + const response = await fetch(`${getBaseUrl()}/api/dashboard/whoami`, { + headers: { + Authorization: `Bearer ${accessToken}`, + }, + }); + + if (!response.ok) { + throw new Error("Failed to fetch user info"); + } + + return (await response.json()) as WhoamiResponse; +} diff --git a/packages/cli/src/commands/docs.ts b/packages/cli/src/commands/docs.ts new file mode 100644 index 0000000..28ee67a --- /dev/null +++ b/packages/cli/src/commands/docs.ts @@ -0,0 +1,241 @@ +import { Command } from "commander"; +import pc from "picocolors"; +import ora from "ora"; + +import { resolveLibrary, getLibraryContext } from "../utils/api.js"; +import { recoverLibraryId } from "../utils/library-id.js"; +import { log } from "../utils/logger.js"; +import { trackEvent } from "../utils/tracking.js"; +import { loadTokens, isTokenExpired } from "../utils/auth.js"; +import type { LibrarySearchResult, ContextResponse } from "../types.js"; + +const isTTY = process.stdout.isTTY; + +function getReputationLabel(score: number | undefined): "High" | "Medium" | "Low" | "Unknown" { + if (score === undefined || score < 0) return "Unknown"; + if (score >= 7) return "High"; + if (score >= 4) return "Medium"; + return "Low"; +} + +function getAccessToken(): string | undefined { + const tokens = loadTokens(); + if (!tokens || isTokenExpired(tokens)) return undefined; + return tokens.access_token; +} + +function formatLibraryResult(lib: LibrarySearchResult, index: number): string { + const lines: string[] = []; + lines.push(`${pc.dim(`${index + 1}.`)} ${pc.bold(`Title: ${lib.title}`)}`); + lines.push(` ${pc.cyan(`Context7-compatible library ID: ${lib.id}`)}`); + + if (lib.description) { + lines.push(` ${pc.dim(`Description: ${lib.description}`)}`); + } + + if (lib.totalSnippets) { + lines.push(` ${pc.dim(`Code Snippets: ${lib.totalSnippets}`)}`); + } + if (lib.trustScore !== undefined) { + lines.push(` ${pc.dim(`Source Reputation: ${getReputationLabel(lib.trustScore)}`)}`); + } + if (lib.benchmarkScore !== undefined && lib.benchmarkScore > 0) { + lines.push(` ${pc.dim(`Benchmark Score: ${lib.benchmarkScore}`)}`); + } + if (lib.versions && lib.versions.length > 0) { + lines.push(` ${pc.dim(`Versions: ${lib.versions.join(", ")}`)}`); + } + + return lines.join("\n"); +} + +async function resolveCommand( + library: string, + query: string | undefined, + options: { json?: boolean } +): Promise { + trackEvent("command", { name: "library" }); + + const spinner = isTTY ? ora(`Searching for "${library}"...`).start() : null; + const accessToken = getAccessToken(); + + let data; + try { + data = await resolveLibrary(library, query, accessToken); + } catch (err) { + spinner?.fail(`Error: ${err instanceof Error ? err.message : String(err)}`); + if (!spinner) log.error(err instanceof Error ? err.message : String(err)); + process.exitCode = 1; + return; + } + + if (data.error) { + spinner?.fail(data.message || data.error); + if (!spinner) log.error(data.message || data.error); + process.exitCode = 1; + return; + } + + if (!data.results || data.results.length === 0) { + spinner?.warn(`No libraries found matching "${library}"`); + if (!spinner) log.warn(`No libraries found matching "${library}"`); + return; + } + + const results = data.results; + + spinner?.stop(); + + if (options.json) { + console.log(JSON.stringify(results, null, 2)); + return; + } + + log.blank(); + + if (data.searchFilterApplied) { + log.warn( + "Your results only include libraries matching your teamspace's library filters. To adjust quality thresholds or blocked libraries, update your filters at https://context7.com/dashboard?tab=policies" + ); + log.blank(); + } + + for (let i = 0; i < results.length; i++) { + log.plain(formatLibraryResult(results[i], i)); + log.blank(); + } + + if (isTTY && results.length > 0) { + const best = results[0]; + log.plain( + `${pc.bold("Quick command:")}\n` + ` ${pc.cyan(`ctx7 docs "${best.id}" ""`)}` + ); + log.blank(); + } +} + +async function queryCommand( + libraryId: string, + query: string, + options: { json?: boolean } +): Promise { + trackEvent("command", { name: "docs" }); + + // Git Bash on Windows rewrites "/owner/repo" into a Windows path; recover it. + libraryId = recoverLibraryId(libraryId); + + if (!libraryId.startsWith("/") || !/^\/[^/]+\/[^/]/.test(libraryId)) { + log.error(`Invalid library ID: "${libraryId}"`); + log.info(`Expected format: /owner/repo or /owner/repo/version (e.g., /facebook/react)`); + log.info(`Run "ctx7 library " to find the correct ID`); + if (process.platform === "win32") { + log.info( + `On Git Bash, prefix the ID with an extra slash to avoid path conversion: ctx7 docs "//facebook/react" ""` + ); + } + process.exitCode = 1; + return; + } + + const accessToken = getAccessToken(); + + const spinner = isTTY ? ora(`Fetching docs for "${libraryId}"...`).start() : null; + const outputType = options.json ? "json" : "txt"; + + let result; + try { + result = await getLibraryContext(libraryId, query, { type: outputType }, accessToken); + } catch (err) { + spinner?.fail(`Error: ${err instanceof Error ? err.message : String(err)}`); + if (!spinner) log.error(err instanceof Error ? err.message : String(err)); + process.exitCode = 1; + return; + } + + if (typeof result === "string") { + spinner?.stop(); + console.log(result); + return; + } + + const ctx = result as ContextResponse; + + if (ctx.error) { + if (ctx.redirectUrl) { + spinner?.warn("Library has been redirected"); + if (!spinner) log.warn("Library has been redirected"); + log.info(`New ID: ${pc.cyan(ctx.redirectUrl)}`); + log.info(`Run: ${pc.cyan(`ctx7 docs "${ctx.redirectUrl}" "${query}"`)}`); + process.exitCode = 1; + return; + } + + spinner?.fail(ctx.message || ctx.error); + if (!spinner) log.error(ctx.message || ctx.error); + process.exitCode = 1; + return; + } + + const total = (ctx.codeSnippets?.length || 0) + (ctx.infoSnippets?.length || 0); + if (total === 0) { + spinner?.warn(`No documentation found for: "${query}"`); + if (!spinner) log.warn(`No documentation found for: "${query}"`); + return; + } + + spinner?.stop(); + + if (options.json) { + console.log(JSON.stringify(ctx, null, 2)); + return; + } + + log.blank(); + + if (ctx.codeSnippets) { + for (const snippet of ctx.codeSnippets) { + log.plain(pc.bold(snippet.codeTitle)); + if (snippet.codeDescription) log.dim(snippet.codeDescription); + log.blank(); + for (const code of snippet.codeList) { + log.plain("```" + code.language); + log.plain(code.code); + log.plain("```"); + log.blank(); + } + } + } + + if (ctx.infoSnippets) { + for (const snippet of ctx.infoSnippets) { + if (snippet.breadcrumb) log.plain(pc.bold(snippet.breadcrumb)); + log.plain(snippet.content); + log.blank(); + } + } +} + +export function registerDocsCommands(program: Command): void { + program + .command("library") + .argument("", "Library name to search for") + .argument("[query]", "Question or task for relevance ranking") + .option("--json", "Output as JSON") + .description("Resolve a library name to a Context7 library ID") + .action(async (name: string, query: string | undefined, options: { json?: boolean }) => { + await resolveCommand(name, query, options); + }); + + program + .command("docs") + .argument("", "Context7 library ID (e.g., /facebook/react)") + .argument( + "", + "Single-topic question to get docs for (run a separate query per distinct concept, unless asking how they interact)" + ) + .option("--json", "Output as JSON") + .description("Query documentation for a library") + .action(async (libraryId: string, query: string, options: { json?: boolean }) => { + await queryCommand(libraryId, query, options); + }); +} diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts new file mode 100644 index 0000000..517e80c --- /dev/null +++ b/packages/cli/src/commands/generate.ts @@ -0,0 +1,563 @@ +import { Command } from "commander"; +import pc from "picocolors"; +import ora from "ora"; +import { mkdir, writeFile, readFile, unlink } from "fs/promises"; +import { join } from "path"; +import { homedir } from "os"; +import { spawn } from "child_process"; +import { input, select } from "@inquirer/prompts"; + +import { + searchLibraries, + getSkillQuestions, + generateSkillStructured, + getSkillQuota, +} from "../utils/api.js"; +import { loadTokens, isTokenExpired } from "../utils/auth.js"; +import { performLogin } from "./auth.js"; +import { log } from "../utils/logger.js"; +import { promptForInstallTargets, getTargetDirs } from "../utils/ide.js"; +import selectOrInput from "../utils/selectOrInput.js"; +import { checkboxWithHover, terminalLink } from "../utils/prompts.js"; +import { trackEvent } from "../utils/tracking.js"; +import { getPreviewsDir } from "../utils/storage-paths.js"; +import type { + GenerateOptions, + LibrarySearchResult, + SkillAnswer, + StructuredGenerateInput, + GenerateStreamEvent, + ToolResultSnippet, +} from "../types.js"; + +interface QueryLogEntry { + query: string; + libraryId?: string; + results: ToolResultSnippet[]; +} + +// TODO(deprecate-skills-phase-2): Remove this deprecated Skill Hub generation +// subcommand after legacy `ctx7 skills generate` support is dropped. +export function registerGenerateCommand(skillCommand: Command): void { + skillCommand + .command("generate") + .alias("gen") + .alias("g") + .option("-o, --output ", "Output directory (default: current directory)") + .option("--all", "Generate for all detected IDEs") + .option("--global", "Generate in global skills directory") + .option("--claude", "Claude Code (.claude/skills/)") + .option("--cursor", "Cursor (.cursor/skills/)") + .option("--universal", "Universal (.agents/skills/)") + .option("--antigravity", "Antigravity (.agent/skills/)") + .description("Generate a skill for a library using AI") + .action(async (options: GenerateOptions) => { + await generateCommand(options); + }); +} + +async function generateCommand(options: GenerateOptions): Promise { + trackEvent("command", { name: "generate" }); + log.blank(); + + let accessToken: string | null = null; + const tokens = loadTokens(); + if (tokens && !isTokenExpired(tokens)) { + accessToken = tokens.access_token; + } else { + log.info("Authentication required. Logging in..."); + log.blank(); + accessToken = await performLogin(); + if (!accessToken) { + log.error("Login failed. Please try again."); + return; + } + log.blank(); + } + + const initSpinner = ora().start(); + const quota = await getSkillQuota(accessToken); + + if (quota.error) { + initSpinner.fail(pc.red("Failed to initialize")); + return; + } + + if (quota.tier !== "unlimited" && quota.remaining < 1) { + initSpinner.fail(pc.red("Weekly skill generation limit reached")); + log.blank(); + console.log( + ` You've used ${pc.bold(pc.white(quota.used.toString()))}/${pc.bold(pc.white(quota.limit.toString()))} skill generations this week.` + ); + console.log( + ` Your quota resets on ${pc.yellow(new Date(quota.resetDate!).toLocaleDateString())}.` + ); + log.blank(); + if (quota.tier === "free") { + console.log( + ` ${pc.yellow("Tip:")} Upgrade to Pro for ${pc.bold("10")} generations per week.` + ); + console.log(` Visit ${pc.green("https://context7.com/dashboard")} to upgrade.`); + } + return; + } + + initSpinner.stop(); + initSpinner.clear(); + + console.log(pc.bold("What should your agent become an expert at?\n")); + console.log( + pc.dim( + "Skills should encode best practices, constraints, and decision-making —\nnot step-by-step tutorials or one-off tasks.\n" + ) + ); + console.log(pc.yellow("Examples:")); + // prettier-ignore + { + console.log(pc.red(' ✕ "Deploy a Next.js app to Vercel"')); + console.log(pc.green(' ✓ "Best practices and constraints for deploying Next.js apps to Vercel"')); + log.blank(); + console.log(pc.red(' ✕ "Use Tailwind for responsive design"')); + console.log(pc.green(' ✓ "Responsive layout decision-making with Tailwind CSS"')); + log.blank(); + console.log(pc.red(' ✕ "Build OAuth with NextAuth"')); + console.log(pc.green(' ✓ "OAuth authentication patterns and pitfalls with NextAuth.js"')); + } + log.blank(); + + let motivation: string; + try { + motivation = await input({ + message: "Describe the expertise:", + }); + + if (!motivation.trim()) { + log.warn("Expertise description is required"); + return; + } + motivation = motivation.trim(); + } catch { + log.warn("Generation cancelled"); + return; + } + + log.blank(); + console.log( + pc.dim( + "To generate this skill, we will read relevant documentation and examples\nfrom Context7.\n" + ) + ); + console.log( + pc.dim( + "These sources are used to:\n• extract best practices and constraints\n• compare patterns across official docs and examples\n• avoid outdated or incorrect guidance\n" + ) + ); + console.log(pc.dim("You can adjust which sources the skill is based on.\n")); + + const searchSpinner = ora("Finding relevant sources...").start(); + const searchResult = await searchLibraries(motivation, accessToken); + + if (searchResult.error || !searchResult.results?.length) { + searchSpinner.fail(pc.red("No sources found")); + log.warn(searchResult.message || "Try a different description"); + return; + } + + searchSpinner.succeed(pc.green(`Found ${searchResult.results.length} relevant sources`)); + log.blank(); + + if (searchResult.searchFilterApplied) { + log.warn( + "Your results only include libraries matching your teamspace's library filters. To adjust quality thresholds or blocked libraries, update your filters at https://context7.com/dashboard?tab=policies" + ); + log.blank(); + } + + let selectedLibraries: LibrarySearchResult[]; + try { + const formatProjectId = (id: string) => { + return id.startsWith("/") ? id.slice(1) : id; + }; + + const isGitHubRepo = (id: string): boolean => { + const cleanId = id.startsWith("/") ? id.slice(1) : id; + const parts = cleanId.split("/"); + if (parts.length !== 2) return false; + const nonGitHubPrefixes = ["websites", "packages", "npm", "docs", "libraries", "llmstxt"]; + return !nonGitHubPrefixes.includes(parts[0].toLowerCase()); + }; + + const libraries = searchResult.results.slice(0, 5); + const indexWidth = libraries.length.toString().length; + const maxNameLen = Math.max(...libraries.map((lib) => lib.title.length)); + + const libraryChoices = libraries.map((lib, index) => { + const projectId = formatProjectId(lib.id); + const isGitHub = isGitHubRepo(lib.id); + const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`); + const paddedName = lib.title.padEnd(maxNameLen); + + const libUrl = `https://context7.com${lib.id}`; + const libLink = terminalLink(lib.title, libUrl, pc.white); + const sourceUrl = isGitHub + ? `https://github.com/${projectId}` + : `https://context7.com${lib.id}`; + const repoLink = terminalLink(projectId, sourceUrl, pc.white); + + const starsLine = + lib.stars && isGitHub ? [`${pc.yellow("Stars:")} ${lib.stars.toLocaleString()}`] : []; + + const metadataLines = [ + pc.dim("─".repeat(50)), + "", + `${pc.yellow("Library:")} ${libLink}`, + `${pc.yellow("Source:")} ${repoLink}`, + `${pc.yellow("Snippets:")} ${lib.totalSnippets.toLocaleString()}`, + ...starsLine, + `${pc.yellow("Description:")}`, + pc.white(lib.description || "No description"), + ]; + + return { + name: `${indexStr} ${paddedName} ${pc.dim(`(${projectId})`)}`, + value: lib, + description: metadataLines.join("\n"), + }; + }); + + selectedLibraries = await checkboxWithHover( + { + message: "Select sources:", + choices: libraryChoices, + pageSize: 10, + loop: false, + }, + { getName: (lib) => `${lib.title} (${formatProjectId(lib.id)})` } + ); + + if (!selectedLibraries || selectedLibraries.length === 0) { + log.info("No sources selected. Try running the command again."); + return; + } + } catch { + log.warn("Generation cancelled"); + return; + } + + log.blank(); + + const questionsSpinner = ora( + "Preparing follow-up questions to clarify scope and constraints..." + ).start(); + const librariesInput = selectedLibraries.map((lib) => ({ id: lib.id, name: lib.title })); + const questionsResult = await getSkillQuestions(librariesInput, motivation, accessToken); + + if (questionsResult.error || !questionsResult.questions?.length) { + questionsSpinner.fail(pc.red("Failed to generate questions")); + log.warn(questionsResult.message || "Please try again"); + return; + } + + questionsSpinner.succeed(pc.green("Questions prepared")); + log.blank(); + + const answers: SkillAnswer[] = []; + try { + for (let i = 0; i < questionsResult.questions.length; i++) { + const q = questionsResult.questions[i]; + const questionNum = i + 1; + const totalQuestions = questionsResult.questions.length; + + const answer = await selectOrInput({ + message: `${pc.dim(`[${questionNum}/${totalQuestions}]`)} ${q.question}`, + options: q.options, + recommendedIndex: q.recommendedIndex, + }); + + answers.push({ + question: q.question, + answer, + }); + + const linesToClear = 3 + q.options.length; + process.stdout.write(`\x1b[${linesToClear}A\x1b[J`); + + const truncatedAnswer = answer.length > 50 ? answer.slice(0, 47) + "..." : answer; + console.log(`${pc.green("✓")} ${pc.dim(`[${questionNum}/${totalQuestions}]`)} ${q.question}`); + console.log(` ${pc.cyan(truncatedAnswer)}`); + log.blank(); + } + } catch { + log.warn("Generation cancelled"); + return; + } + + let generatedContent: string | null = null; + let skillName: string = ""; + let feedback: string | undefined; + let previewFile: string | null = null; + let previewFileWritten = false; + + const cleanupPreviewFile = async () => { + if (previewFile) { + await unlink(previewFile).catch(() => {}); + } + }; + + const queryLog: QueryLogEntry[] = []; + let genSpinner: ReturnType | null = null; + + const formatQueryLogText = (): string => { + if (queryLog.length === 0) return ""; + + const lines: string[] = []; + const latestEntry = queryLog[queryLog.length - 1]; + + lines.push(""); + + for (const result of latestEntry.results.slice(0, 3)) { + const cleanContent = result.content.replace(/Source:\s*https?:\/\/[^\s]+/gi, "").trim(); + if (cleanContent) { + lines.push(` ${pc.yellow("•")} ${pc.white(result.title)}`); + const maxLen = 400; + const content = + cleanContent.length > maxLen ? cleanContent.slice(0, maxLen - 3) + "..." : cleanContent; + const words = content.split(" "); + let currentLine = " "; + for (const word of words) { + if (currentLine.length + word.length > 84) { + lines.push(pc.dim(currentLine)); + currentLine = " " + word + " "; + } else { + currentLine += word + " "; + } + } + if (currentLine.trim()) { + lines.push(pc.dim(currentLine)); + } + lines.push(""); + } + } + + return "\n" + lines.join("\n"); + }; + + let isGeneratingContent = false; + let initialStatus = "Reading selected Context7 sources to generate the skill..."; + + const handleStreamEvent = (event: GenerateStreamEvent) => { + if (event.type === "progress") { + if (genSpinner) { + if (event.message.startsWith("Generating skill content...") && !isGeneratingContent) { + isGeneratingContent = true; + if (queryLog.length > 0) { + genSpinner.succeed(pc.green(`Read Context7 sources`)); + } else { + genSpinner.succeed(pc.green(`Ready to generate`)); + } + genSpinner = ora("Generating skill content...").start(); + } else if (!isGeneratingContent) { + genSpinner.text = initialStatus + formatQueryLogText(); + } + } + } else if (event.type === "tool_result") { + queryLog.push({ + query: event.query, + libraryId: event.libraryId, + results: event.results, + }); + if (genSpinner && !isGeneratingContent) { + genSpinner.text = genSpinner.text.split("\n")[0] + formatQueryLogText(); + } + } + }; + + while (true) { + const generateInput: StructuredGenerateInput = { + motivation, + libraries: librariesInput, + answers, + feedback, + previousContent: feedback && generatedContent ? generatedContent : undefined, + }; + + queryLog.length = 0; + isGeneratingContent = false; + previewFileWritten = false; + initialStatus = feedback + ? "Regenerating skill with your feedback..." + : "Reading selected Context7 sources to generate the skill..."; + + genSpinner = ora(initialStatus).start(); + + const result = await generateSkillStructured(generateInput, handleStreamEvent, accessToken); + + if (result.error) { + genSpinner.fail(pc.red(`Error: ${result.error}`)); + return; + } + + if (!result.content) { + genSpinner.fail(pc.red("No content generated")); + return; + } + + genSpinner.succeed(pc.green(`Generated skill for "${result.libraryName}"`)); + generatedContent = result.content; + skillName = result.libraryName.toLowerCase().replace(/[^a-z0-9-]/g, "-"); + + const contentLines = generatedContent.split("\n"); + const previewLineCount = 20; + const hasMoreLines = contentLines.length > previewLineCount; + const previewContent = contentLines.slice(0, previewLineCount).join("\n"); + const remainingLines = contentLines.length - previewLineCount; + + const showPreview = () => { + log.blank(); + console.log(pc.dim("━".repeat(70))); + console.log(pc.bold(`Generated Skill: `) + pc.green(pc.bold(skillName))); + console.log(pc.dim("━".repeat(70))); + log.blank(); + console.log(previewContent); + if (hasMoreLines) { + log.blank(); + console.log(pc.dim(`... ${remainingLines} more lines`)); + } + log.blank(); + console.log(pc.dim("━".repeat(70))); + log.blank(); + }; + + const openInEditor = async () => { + const previewDir = getPreviewsDir(); + await mkdir(previewDir, { recursive: true }); + previewFile = join(previewDir, `${skillName}.md`); + if (!previewFileWritten) { + await writeFile(previewFile, generatedContent!, "utf-8"); + previewFileWritten = true; + } + const editor = process.env.EDITOR || "open"; + await new Promise((resolve) => { + const child = spawn(editor, [previewFile!], { + stdio: "inherit", + }); + child.on("close", () => resolve()); + }); + }; + + const syncFromPreviewFile = async () => { + if (previewFile) { + generatedContent = await readFile(previewFile, "utf-8"); + } + }; + + showPreview(); + + await new Promise((resolve) => setTimeout(resolve, 100)); + + try { + let action: string; + while (true) { + const choices = [ + { name: `${pc.green("✓")} Install skill (save locally)`, value: "install" }, + { name: `${pc.blue("⤢")} Edit skill in editor`, value: "view" }, + { name: `${pc.yellow("✎")} Request changes`, value: "feedback" }, + { name: `${pc.red("✕")} Cancel`, value: "cancel" }, + ]; + + action = await select({ + message: "What would you like to do?", + choices, + }); + + if (action === "view") { + await openInEditor(); + continue; + } + await syncFromPreviewFile(); + break; + } + + if (action === "install") { + break; + } else if (action === "cancel") { + await cleanupPreviewFile(); + log.warn("Generation cancelled"); + return; + } else if (action === "feedback") { + trackEvent("gen_feedback"); + feedback = await input({ + message: "What changes would you like? (press Enter to skip)", + }); + + if (!feedback.trim()) { + feedback = undefined; + } + log.blank(); + } + } catch { + await cleanupPreviewFile(); + log.warn("Generation cancelled"); + return; + } + } + + const targets = await promptForInstallTargets(options); + if (!targets) { + log.warn("Generation cancelled"); + return; + } + + const targetDirs = getTargetDirs(targets); + + const writeSpinner = ora("Writing skill files...").start(); + + let permissionError = false; + const failedDirs: Set = new Set(); + + for (const targetDir of targetDirs) { + let finalDir = targetDir; + if (options.output && !targetDir.includes("/.config/") && !targetDir.startsWith(homedir())) { + finalDir = targetDir.replace(process.cwd(), options.output); + } + const skillDir = join(finalDir, skillName); + const skillPath = join(skillDir, "SKILL.md"); + + try { + await mkdir(skillDir, { recursive: true }); + await writeFile(skillPath, generatedContent!, "utf-8"); + } catch (err) { + const error = err as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + permissionError = true; + failedDirs.add(skillDir); + } else { + log.warn(`Failed to write to ${skillPath}: ${error.message}`); + } + } + } + + if (permissionError) { + writeSpinner.fail(pc.red("Permission denied")); + log.blank(); + console.log(pc.yellow("Fix permissions with:")); + for (const dir of failedDirs) { + const parentDir = join(dir, ".."); + console.log(pc.dim(` sudo chown -R $(whoami) "${parentDir}"`)); + } + log.blank(); + return; + } + + writeSpinner.succeed(pc.green(`Created skill in ${targetDirs.length} location(s)`)); + trackEvent("gen_install"); + + log.blank(); + console.log(pc.green("Skill saved successfully")); + for (const targetDir of targetDirs) { + console.log(pc.dim(` ${targetDir}/`) + pc.green(skillName)); + } + log.blank(); + + await cleanupPreviewFile(); +} diff --git a/packages/cli/src/commands/remove.ts b/packages/cli/src/commands/remove.ts new file mode 100644 index 0000000..4d923ee --- /dev/null +++ b/packages/cli/src/commands/remove.ts @@ -0,0 +1,527 @@ +import { Command } from "commander"; +import pc from "picocolors"; +import ora from "ora"; +import { checkboxWithHover } from "../utils/prompts.js"; +import { log } from "../utils/logger.js"; +import { trackEvent } from "../utils/tracking.js"; +import { ALL_AGENT_NAMES, SETUP_AGENT_NAMES, getAgent, type SetupAgent } from "../setup/agents.js"; +import { + readJsonConfig, + readTomlServerExists, + removeServerEntry, + writeJsonConfig, + resolveMcpPath, + removeTomlServer, +} from "../setup/mcp-writer.js"; +import { join } from "path"; +import { access, readFile, rm, writeFile } from "fs/promises"; + +type Scope = "global" | "project"; +type UninstallMode = "mcp" | "cli"; + +interface UninstallOptions { + claude?: boolean; + cursor?: boolean; + opencode?: boolean; + codex?: boolean; + antigravity?: boolean; + gemini?: boolean; + project?: boolean; + yes?: boolean; + all?: boolean; + cli?: boolean; + mcp?: boolean; +} + +interface CleanupStatus { + status: string; + path: string; +} + +interface SkillCleanupStatus extends CleanupStatus { + name: string; +} + +interface AgentCleanupResult { + agent: string; + mcp?: CleanupStatus; + rule?: CleanupStatus; + skills?: SkillCleanupStatus[]; +} + +const CHECKBOX_THEME = { + style: { + highlight: (text: string) => pc.green(text), + disabledChoice: (text: string) => ` ${pc.dim("◯")} ${pc.dim(text)}`, + }, +}; + +const CONTEXT7_SECTION_MARKER = ""; +const MODE_SKILLS: Record = { + mcp: ["context7-mcp"], + cli: ["find-docs"], +}; + +const MODE_LABELS: Record = { + mcp: "MCP", + cli: "CLI + Skills", +}; + +export function registerRemoveCommand(program: Command): void { + program + .command("remove") + .alias("uninstall") + .description("Remove Context7 setup from your AI coding agent") + .option("--claude", "Remove from Claude Code") + .option("--cursor", "Remove from Cursor") + .option("--opencode", "Remove from OpenCode") + .option("--codex", "Remove from Codex") + .option("--antigravity", "Remove from Antigravity") + .option("--gemini", "Remove from Gemini CLI") + .option("--all", "Remove both MCP setup and CLI + Skills setup") + .option("--mcp", "Remove MCP setup") + .option("--cli", "Remove CLI + Skills setup") + .option("-p, --project", "Remove from the current project instead of global config") + .option("-y, --yes", "Skip confirmation prompts") + .action(async (options: UninstallOptions) => { + await removeCommand(options); + }); +} + +function getSelectedAgents(options: UninstallOptions): SetupAgent[] { + const agents: SetupAgent[] = []; + if (options.claude) agents.push("claude"); + if (options.cursor) agents.push("cursor"); + if (options.opencode) agents.push("opencode"); + if (options.codex) agents.push("codex"); + if (options.antigravity) agents.push("antigravity"); + if (options.gemini) agents.push("gemini"); + return agents; +} + +async function promptAgents(detected: SetupAgent[]): Promise { + const choices = detected.map((name) => ({ + name: SETUP_AGENT_NAMES[name], + value: name, + })); + + if (detected.length > 0) { + log.dim(`Detected: ${detected.map((agent) => SETUP_AGENT_NAMES[agent]).join(", ")}`); + } + + try { + return await checkboxWithHover( + { + message: "Which agents do you want to remove Context7 setup from?", + choices, + loop: false, + theme: CHECKBOX_THEME, + }, + { getName: (agent: SetupAgent) => SETUP_AGENT_NAMES[agent] } + ); + } catch { + return null; + } +} + +async function promptModes(modes: UninstallMode[]): Promise { + const choices = modes.map((mode) => ({ + name: MODE_LABELS[mode], + value: mode, + })); + + try { + return await checkboxWithHover( + { + message: "Which Context7 setup modes do you want to remove?", + choices, + loop: false, + theme: CHECKBOX_THEME, + }, + { getName: (mode: UninstallMode) => MODE_LABELS[mode] } + ); + } catch { + return null; + } +} + +async function resolveAgents(options: UninstallOptions, scope: Scope): Promise { + const explicit = getSelectedAgents(options); + if (explicit.length > 0) return explicit; + + const detected = await detectConfiguredAgents(scope); + if (detected.length > 0 && options.yes) return detected; + + if (detected.length === 0) { + log.warn( + "No Context7 setup detected. Pass --claude, --cursor, --opencode, --codex, --antigravity, or --gemini." + ); + return []; + } + + log.blank(); + const selected = await promptAgents(detected); + if (!selected) { + log.warn("Remove cancelled"); + return []; + } + + return selected; +} + +function resolveFlagModes(options: UninstallOptions): UninstallMode[] { + if (options.all) return ["mcp", "cli"]; + + const selected: UninstallMode[] = []; + + if (options.mcp) selected.push("mcp"); + if (options.cli) selected.push("cli"); + + return selected.length > 0 ? selected : ["mcp", "cli"]; +} + +async function pathExists(path: string): Promise { + try { + await access(path); + return true; + } catch { + return false; + } +} + +async function hasMcpConfig(agentName: SetupAgent, scope: Scope): Promise { + const agent = getAgent(agentName); + // Agents with no project-level MCP (e.g. Antigravity) only have a global + // config — there's nothing to detect at project scope. + if (scope === "project" && agent.mcp.projectPaths.length === 0) return false; + const candidates = + scope === "global" + ? agent.mcp.globalPaths + : agent.mcp.projectPaths.map((path) => join(process.cwd(), path)); + const mcpPath = await resolveMcpPath(candidates); + + if (mcpPath.endsWith(".toml")) { + return readTomlServerExists(mcpPath, "context7"); + } + + let existing: Record; + try { + existing = await readJsonConfig(mcpPath); + } catch (err) { + log.warn( + `Skipped ${mcpPath}: could not parse (${err instanceof Error ? err.message : String(err)})` + ); + return false; + } + const section = existing[agent.mcp.configKey]; + return ( + !!section && typeof section === "object" && !Array.isArray(section) && "context7" in section + ); +} + +async function hasRule(agentName: SetupAgent, scope: Scope): Promise { + const agent = getAgent(agentName); + const rule = agent.rule; + + if (rule.kind === "file") { + const ruleDir = + scope === "global" ? rule.dir("global") : join(process.cwd(), rule.dir("project")); + return pathExists(join(ruleDir, rule.filename)); + } + + const filePath = + scope === "global" ? rule.file("global") : join(process.cwd(), rule.file("project")); + + try { + const existing = await readFile(filePath, "utf-8"); + return existing.includes(CONTEXT7_SECTION_MARKER); + } catch { + return false; + } +} + +async function hasSkill(agentName: SetupAgent, scope: Scope, skillName: string): Promise { + const agent = getAgent(agentName); + const skillsDir = + scope === "global" + ? agent.skill.dir("global") + : join(process.cwd(), agent.skill.dir("project")); + return pathExists(join(skillsDir, skillName)); +} + +async function detectAvailableModes(agents: SetupAgent[], scope: Scope): Promise { + let hasMcpArtifacts = false; + let hasCliArtifacts = false; + let hasRuleArtifacts = false; + + for (const agent of agents) { + hasMcpArtifacts = + hasMcpArtifacts || + (await hasMcpConfig(agent, scope)) || + (await hasSkill(agent, scope, MODE_SKILLS.mcp[0])); + hasCliArtifacts = hasCliArtifacts || (await hasSkill(agent, scope, MODE_SKILLS.cli[0])); + hasRuleArtifacts = hasRuleArtifacts || (await hasRule(agent, scope)); + } + + const modes: UninstallMode[] = []; + if (hasMcpArtifacts) modes.push("mcp"); + if (hasCliArtifacts) modes.push("cli"); + + if (modes.length === 0 && hasRuleArtifacts) { + return ["mcp", "cli"]; + } + + return modes; +} + +async function hasAnyContext7Artifacts(agent: SetupAgent, scope: Scope): Promise { + return ( + (await hasMcpConfig(agent, scope)) || + (await hasRule(agent, scope)) || + (await hasSkill(agent, scope, MODE_SKILLS.mcp[0])) || + (await hasSkill(agent, scope, MODE_SKILLS.cli[0])) + ); +} + +async function detectConfiguredAgents(scope: Scope): Promise { + const detected: SetupAgent[] = []; + + for (const agent of ALL_AGENT_NAMES) { + if (await hasAnyContext7Artifacts(agent, scope)) { + detected.push(agent); + } + } + + return detected; +} + +async function resolveModes( + options: UninstallOptions, + agents: SetupAgent[], + scope: Scope +): Promise { + if (options.all || options.mcp || options.cli) { + return resolveFlagModes(options); + } + + const detectedModes = await detectAvailableModes(agents, scope); + if (detectedModes.length <= 1) { + return detectedModes.length === 1 ? detectedModes : ["mcp", "cli"]; + } + + if (options.yes) { + return detectedModes; + } + + log.blank(); + const selected = await promptModes(detectedModes); + if (!selected) { + log.warn("Remove cancelled"); + return []; + } + + return selected; +} + +async function uninstallMcp(agentName: SetupAgent, scope: Scope): Promise { + const agent = getAgent(agentName); + if (scope === "project" && agent.mcp.projectPaths.length === 0) { + return { status: "not found", path: "" }; + } + const mcpCandidates = + scope === "global" + ? agent.mcp.globalPaths + : agent.mcp.projectPaths.map((path) => join(process.cwd(), path)); + const mcpPath = await resolveMcpPath(mcpCandidates); + + try { + if (mcpPath.endsWith(".toml")) { + const { removed } = await removeTomlServer(mcpPath, "context7"); + return { status: removed ? "removed" : "not found", path: mcpPath }; + } + + const existing = await readJsonConfig(mcpPath); + const { config, removed } = removeServerEntry(existing, agent.mcp.configKey, "context7"); + if (removed) { + await writeJsonConfig(mcpPath, config); + } + return { status: removed ? "removed" : "not found", path: mcpPath }; + } catch (err) { + return { status: `failed: ${err instanceof Error ? err.message : String(err)}`, path: mcpPath }; + } +} + +async function uninstallRule(agentName: SetupAgent, scope: Scope): Promise { + const agent = getAgent(agentName); + const rule = agent.rule; + + if (rule.kind === "file") { + const rulePath = + scope === "global" ? rule.dir("global") : join(process.cwd(), rule.dir("project")); + const targetPath = join(rulePath, rule.filename); + + try { + await rm(targetPath); + return { status: "removed", path: targetPath }; + } catch (err) { + const error = err as NodeJS.ErrnoException; + if (error.code === "ENOENT") return { status: "not found", path: targetPath }; + return { status: `failed: ${error.message}`, path: targetPath }; + } + } + + const filePath = + scope === "global" ? rule.file("global") : join(process.cwd(), rule.file("project")); + + try { + const existing = await readFile(filePath, "utf-8"); + if (!existing.includes(CONTEXT7_SECTION_MARKER)) { + return { status: "not found", path: filePath }; + } + + const escapedMarker = CONTEXT7_SECTION_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const updated = existing + .replace(new RegExp(`\\n?${escapedMarker}\\n[\\s\\S]*?${escapedMarker}\\n?`, "m"), "") + .replace(/\n{3,}/g, "\n\n") + .replace(/^\n+/, "") + .trimEnd(); + + if (updated.length === 0) { + await rm(filePath); + } else { + await writeFile(filePath, `${updated}\n`, "utf-8"); + } + + return { status: "removed", path: filePath }; + } catch (err) { + const error = err as NodeJS.ErrnoException; + if (error.code === "ENOENT") return { status: "not found", path: filePath }; + return { status: `failed: ${error.message}`, path: filePath }; + } +} + +async function uninstallSkills( + agentName: SetupAgent, + scope: Scope, + skillNames: readonly string[] +): Promise { + const agent = getAgent(agentName); + const skillsDir = + scope === "global" + ? agent.skill.dir("global") + : join(process.cwd(), agent.skill.dir("project")); + + const results: SkillCleanupStatus[] = []; + + for (const skillName of skillNames) { + const skillPath = join(skillsDir, skillName); + try { + await rm(skillPath, { recursive: true }); + results.push({ name: skillName, status: "removed", path: skillPath }); + } catch (err) { + const error = err as NodeJS.ErrnoException; + if (error.code === "ENOENT") { + results.push({ name: skillName, status: "not found", path: skillPath }); + } else { + results.push({ name: skillName, status: `failed: ${error.message}`, path: skillPath }); + } + } + } + + return results; +} + +async function uninstallAgent( + agentName: SetupAgent, + scope: Scope, + modes: UninstallMode[] +): Promise { + const result: AgentCleanupResult = { agent: getAgent(agentName).displayName }; + const skillNames = Array.from(new Set(modes.flatMap((mode) => [...MODE_SKILLS[mode]]))); + const shouldRemoveRule = modes.includes("mcp") || modes.includes("cli"); + + if (modes.includes("mcp")) { + result.mcp = await uninstallMcp(agentName, scope); + } + + if (shouldRemoveRule) { + result.rule = await uninstallRule(agentName, scope); + } + + if (skillNames.length > 0) { + result.skills = await uninstallSkills(agentName, scope, skillNames); + } + + return result; +} + +function iconForStatus(status: string): string { + if (status === "removed") return pc.green("-"); + if (status === "not found") return pc.dim("~"); + return pc.red("!"); +} + +function printResults(results: AgentCleanupResult[], modes: UninstallMode[]): void { + log.blank(); + const shouldPrintRule = modes.includes("mcp") || modes.includes("cli"); + let hasVisibleResults = false; + + for (const result of results) { + const visibleSkills = result.skills?.filter((skill) => skill.status !== "not found") ?? []; + const showMcp = modes.includes("mcp") && result.mcp && result.mcp.status !== "not found"; + const showRule = shouldPrintRule && result.rule && result.rule.status !== "not found"; + + if (!showMcp && !showRule && visibleSkills.length === 0) { + continue; + } + + hasVisibleResults = true; + log.plain(` ${pc.bold(result.agent)}`); + + if (showMcp && result.mcp) { + log.plain(` ${iconForStatus(result.mcp.status)} MCP config ${result.mcp.status}`); + log.plain(` ${pc.dim(result.mcp.path)}`); + } + + if (showRule && result.rule) { + log.plain(` ${iconForStatus(result.rule.status)} Rule ${result.rule.status}`); + log.plain(` ${pc.dim(result.rule.path)}`); + } + + for (const skill of visibleSkills) { + log.plain(` ${iconForStatus(skill.status)} Skill ${skill.name} ${skill.status}`); + log.plain(` ${pc.dim(skill.path)}`); + } + } + + if (hasVisibleResults) { + log.blank(); + } else { + log.plain(` ${pc.dim("No matching Context7 setup was found to remove.")}`); + log.blank(); + } +} + +async function removeCommand(options: UninstallOptions): Promise { + trackEvent("command", { name: "remove" }); + + const scope: Scope = options.project ? "project" : "global"; + const agents = await resolveAgents(options, scope); + if (agents.length === 0) return; + const modes = await resolveModes(options, agents, scope); + if (modes.length === 0) return; + + log.blank(); + const spinner = ora("Removing Context7 setup...").start(); + + const results: AgentCleanupResult[] = []; + for (const agentName of agents) { + spinner.text = `Cleaning up ${getAgent(agentName).displayName}...`; + results.push(await uninstallAgent(agentName, scope, modes)); + } + + spinner.succeed("Context7 cleanup complete"); + printResults(results, modes); + + trackEvent("remove", { agents, scope, modes }); +} diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.ts new file mode 100644 index 0000000..c5b8a3f --- /dev/null +++ b/packages/cli/src/commands/setup.ts @@ -0,0 +1,550 @@ +import { Command } from "commander"; +import pc from "picocolors"; +import ora from "ora"; +import { select } from "@inquirer/prompts"; +import { mkdir, readFile, writeFile } from "fs/promises"; +import { dirname, join } from "path"; +import { randomBytes } from "crypto"; + +import { log } from "../utils/logger.js"; +import { checkboxWithHover } from "../utils/prompts.js"; +import { trackEvent } from "../utils/tracking.js"; +import { getBaseUrl, downloadSkill } from "../utils/api.js"; +import { installSkillFiles } from "../utils/installer.js"; +import { performLogin } from "./auth.js"; +import { saveTokens, getValidAccessToken } from "../utils/auth.js"; +import { + type SetupAgent, + type AuthOptions, + type Transport, + SETUP_AGENT_NAMES, + AUTH_MODE_LABELS, + ALL_AGENT_NAMES, + getAgent, + detectAgents, +} from "../setup/agents.js"; +import { customizeSkillFilesForAgent, getRuleContent } from "../setup/templates.js"; +import { + readJsonConfig, + mergeServerEntry, + writeJsonConfig, + resolveMcpPath, + appendTomlServer, + readTomlServerEntry, + isStdioContext7Entry, + patchStdioApiKey, + getJsonServerEntry, +} from "../setup/mcp-writer.js"; + +type Scope = "global" | "project"; +type SetupMode = "mcp" | "cli"; + +interface SetupOptions { + claude?: boolean; + cursor?: boolean; + antigravity?: boolean; + opencode?: boolean; + codex?: boolean; + gemini?: boolean; + project?: boolean; + yes?: boolean; + apiKey?: string; + oauth?: boolean; + cli?: boolean; + mcp?: boolean; + stdio?: boolean; +} + +function resolveTransport(options: SetupOptions): Transport { + return options.stdio ? "stdio" : "http"; +} + +const CHECKBOX_THEME = { + style: { + highlight: (text: string) => pc.green(text), + disabledChoice: (text: string) => ` ${pc.dim("◯")} ${pc.dim(text)}`, + }, +}; + +function getSelectedAgents(options: SetupOptions): SetupAgent[] { + const agents: SetupAgent[] = []; + if (options.claude) agents.push("claude"); + if (options.cursor) agents.push("cursor"); + if (options.opencode) agents.push("opencode"); + if (options.codex) agents.push("codex"); + if (options.antigravity) agents.push("antigravity"); + if (options.gemini) agents.push("gemini"); + return agents; +} + +export function registerSetupCommand(program: Command): void { + program + .command("setup") + .description("Set up Context7 for your AI coding agent") + .option("--claude", "Set up for Claude Code") + .option("--cursor", "Set up for Cursor") + .option("--antigravity", "Set up for Antigravity (.agent/skills)") + .option("--opencode", "Set up for OpenCode") + .option("--codex", "Set up for Codex") + .option("--gemini", "Set up for Gemini CLI") + .option("--mcp", "Set up MCP server mode") + .option("--cli", "Set up CLI + Skills mode (no MCP server)") + .option("-p, --project", "Configure for current project instead of globally") + .option("-y, --yes", "Skip confirmation prompts") + .option("--api-key ", "Use API key authentication") + .option("--oauth", "Use OAuth endpoint (IDE handles auth flow)") + .option("--stdio", "Configure the MCP server as a local stdio process (default: HTTP)") + .action(async (options: SetupOptions) => { + await setupCommand(options); + }); +} + +async function authenticateAndGenerateKey(): Promise { + const accessToken = (await getValidAccessToken()) ?? (await performLogin()); + + if (!accessToken) return null; + + const spinner = ora("Configuring authentication...").start(); + + try { + const response = await fetch(`${getBaseUrl()}/api/dashboard/api-keys`, { + method: "POST", + headers: { + Authorization: `Bearer ${accessToken}`, + "Content-Type": "application/json", + }, + body: JSON.stringify({ name: `ctx7-cli-${randomBytes(3).toString("hex")}` }), + }); + + if (!response.ok) { + const err = (await response.json().catch(() => ({}))) as { message?: string; error?: string }; + spinner.fail("Authentication failed"); + log.error(err.message || err.error || `HTTP ${response.status}`); + return null; + } + + const result = (await response.json()) as { data: { apiKey: string } }; + spinner.succeed("Authenticated"); + return result.data.apiKey; + } catch (err) { + spinner.fail("Authentication failed"); + log.error(err instanceof Error ? err.message : String(err)); + return null; + } +} + +async function resolveAuth(options: SetupOptions): Promise { + if (options.apiKey) return { mode: "api-key", apiKey: options.apiKey }; + if (options.oauth) return { mode: "oauth" }; + + const apiKey = await authenticateAndGenerateKey(); + if (!apiKey) return null; + return { mode: "api-key", apiKey }; +} + +async function resolveMode(options: SetupOptions): Promise { + if (options.cli) return "cli"; + if (options.mcp || options.yes || options.oauth || options.stdio) return "mcp"; + + return select({ + message: "How should your agent access Context7?", + choices: [ + { + name: `MCP server\n ${pc.dim("Agent calls Context7 tools via MCP protocol to retrieve up-to-date library docs")}`, + value: "mcp" as SetupMode, + }, + { + name: `CLI + Skills\n ${pc.dim("Installs a find-docs skill that guides your agent to fetch up-to-date library docs using ")}${pc.dim(pc.bold("ctx7"))}${pc.dim(" CLI commands")}`, + value: "cli" as SetupMode, + }, + ], + theme: { + style: { + highlight: (text: string) => pc.green(text), + answer: (text: string) => pc.green(text.split("\n")[0].trim()), + }, + }, + }); +} + +async function resolveCliAuth(apiKey?: string): Promise { + if (apiKey) { + saveTokens({ access_token: apiKey, token_type: "bearer" }); + log.blank(); + log.plain(`${pc.green("✔")} Authenticated`); + return; + } + + const validToken = await getValidAccessToken(); + if (validToken) { + log.blank(); + log.plain(`${pc.green("✔")} Authenticated`); + return; + } + + await performLogin(); +} + +async function promptAgents(): Promise { + const choices = ALL_AGENT_NAMES.map((name) => ({ + name: SETUP_AGENT_NAMES[name], + value: name, + })); + + const message = "Which agents do you want to set up?"; + + try { + return await checkboxWithHover( + { + message, + choices, + loop: false, + theme: CHECKBOX_THEME, + }, + { getName: (a: SetupAgent) => SETUP_AGENT_NAMES[a] } + ); + } catch { + return null; + } +} + +async function resolveAgents(options: SetupOptions, scope: Scope): Promise { + const explicit = getSelectedAgents(options); + if (explicit.length > 0) return explicit; + + const detected = await detectAgents(scope); + + if (detected.length > 0 && options.yes) return detected; + + log.blank(); + const selected = await promptAgents(); + if (!selected) { + log.warn("Setup cancelled"); + return []; + } + return selected; +} + +/** Install a rule for an agent, handling both "file" (standalone) and "append" (AGENTS.md) types. */ +async function installRule( + agentName: SetupAgent, + mode: SetupMode, + scope: Scope +): Promise<{ status: string; path: string }> { + const agent = getAgent(agentName); + const rule = agent.rule; + const content = await getRuleContent(mode, agentName); + + if (rule.kind === "file") { + const ruleDir = + scope === "global" ? rule.dir("global") : join(process.cwd(), rule.dir("project")); + const rulePath = join(ruleDir, rule.filename); + await mkdir(dirname(rulePath), { recursive: true }); + await writeFile(rulePath, content, "utf-8"); + return { status: "installed", path: rulePath }; + } + + const filePath = + scope === "global" ? rule.file("global") : join(process.cwd(), rule.file("project")); + const escapedMarker = rule.sectionMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const section = `${rule.sectionMarker}\n${content}${rule.sectionMarker}`; + + let existing = ""; + try { + existing = await readFile(filePath, "utf-8"); + } catch { + // File doesn't exist yet + } + + if (existing.includes(rule.sectionMarker)) { + const regex = new RegExp(`${escapedMarker}\\n[\\s\\S]*?${escapedMarker}`); + const updated = existing.replace(regex, section); + await writeFile(filePath, updated, "utf-8"); + return { status: "updated", path: filePath }; + } + + const separator = + existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : ""; + await mkdir(dirname(filePath), { recursive: true }); + await writeFile(filePath, existing + separator + section + "\n", "utf-8"); + return { status: "installed", path: filePath }; +} + +/** + * For stdio transport, preserve an existing `@upstash/context7-mcp` invocation + * (e.g., `@upstash/context7-mcp@latest` or a user-pinned version) and only + * swap the `--api-key` value. Falls back to the agent's canonical shape when + * no existing stdio entry is detected. HTTP transport always uses the + * canonical shape. + */ +function resolveEntryToWrite( + agent: ReturnType, + auth: AuthOptions, + transport: Transport, + existingEntry: Record | undefined +): Record { + if (transport === "stdio" && existingEntry && isStdioContext7Entry(existingEntry)) { + const apiKey = auth.mode === "api-key" ? auth.apiKey : undefined; + return patchStdioApiKey(existingEntry, apiKey); + } + return agent.mcp.buildEntry(auth, transport); +} + +async function setupAgent( + agentName: SetupAgent, + auth: AuthOptions, + transport: Transport, + scope: Scope +): Promise<{ + agent: string; + mcpStatus: string; + mcpPath: string; + ruleStatus: string; + rulePath: string; + skillStatus: string; + skillPath: string; +}> { + const agent = getAgent(agentName); + + const mcpCandidates = + scope === "global" || agent.mcp.projectPaths.length === 0 + ? agent.mcp.globalPaths + : agent.mcp.projectPaths.map((p) => join(process.cwd(), p)); + const mcpPath = await resolveMcpPath(mcpCandidates); + + let mcpStatus: string; + try { + if (mcpPath.endsWith(".toml")) { + const existingTomlEntry = + transport === "stdio" ? await readTomlServerEntry(mcpPath, "context7") : undefined; + const entry = resolveEntryToWrite(agent, auth, transport, existingTomlEntry); + const { alreadyExists } = await appendTomlServer(mcpPath, "context7", entry); + mcpStatus = alreadyExists + ? `reconfigured with ${AUTH_MODE_LABELS[auth.mode]}` + : `configured with ${AUTH_MODE_LABELS[auth.mode]}`; + } else { + const existing = await readJsonConfig(mcpPath); + const existingJsonEntry = + transport === "stdio" + ? getJsonServerEntry(existing, agent.mcp.configKey, "context7") + : undefined; + const entry = resolveEntryToWrite(agent, auth, transport, existingJsonEntry); + const { config, alreadyExists } = mergeServerEntry( + existing, + agent.mcp.configKey, + "context7", + entry + ); + mcpStatus = alreadyExists + ? `reconfigured with ${AUTH_MODE_LABELS[auth.mode]}` + : `configured with ${AUTH_MODE_LABELS[auth.mode]}`; + await writeJsonConfig(mcpPath, config); + } + } catch (err) { + mcpStatus = `failed: ${err instanceof Error ? err.message : String(err)}`; + } + + let ruleStatus: string; + let rulePath: string; + try { + const result = await installRule(agentName, "mcp", scope); + ruleStatus = result.status; + rulePath = result.path; + } catch (err) { + ruleStatus = `failed: ${err instanceof Error ? err.message : String(err)}`; + rulePath = ""; + } + + const skillDir = + scope === "global" + ? agent.skill.dir("global") + : join(process.cwd(), agent.skill.dir("project")); + const skillPath = join(skillDir, agent.skill.name, "SKILL.md"); + + let skillStatus: string; + try { + const downloadData = await downloadSkill("/upstash/context7", agent.skill.name); + if (downloadData.error || downloadData.files.length === 0) { + throw new Error(downloadData.error || "no files"); + } + await installSkillFiles(agent.skill.name, downloadData.files, skillDir); + skillStatus = "installed"; + } catch (err) { + skillStatus = `failed: ${err instanceof Error ? err.message : String(err)}`; + } + + return { + agent: agent.displayName, + mcpStatus, + mcpPath, + ruleStatus, + rulePath, + skillStatus, + skillPath, + }; +} + +function logSkillStatus(skillStatus: string, skillPath: string): void { + const skillFailed = skillStatus.startsWith("failed:"); + const skillIcon = + skillStatus === "installed" ? pc.green("+") : skillFailed ? pc.red("✖") : pc.dim("~"); + log.plain(` ${skillIcon} Skill ${skillFailed ? "failed" : skillStatus}`); + log.plain(` ${pc.dim(skillPath)}`); + if (skillFailed) { + log.plain(` ${pc.red(skillStatus.slice("failed: ".length))}`); + if (skillStatus.includes("EACCES")) { + log.plain( + ` ${pc.yellow("tip:")} fix permissions with: ${pc.cyan(`sudo chown -R $(whoami) ${dirname(dirname(skillPath))}`)}` + ); + } + } +} + +async function setupMcp(agents: SetupAgent[], options: SetupOptions, scope: Scope): Promise { + const transport = resolveTransport(options); + if (transport === "stdio" && options.oauth) { + log.error("--stdio is incompatible with --oauth (OAuth uses the hosted HTTP endpoint)."); + return; + } + + const auth = await resolveAuth(options); + if (!auth) { + log.warn("Setup cancelled"); + return; + } + + log.blank(); + const spinner = ora("Setting up Context7...").start(); + + const results = []; + for (const agentName of agents) { + spinner.text = `Setting up ${getAgent(agentName).displayName}...`; + results.push(await setupAgent(agentName, auth, transport, scope)); + } + + spinner.succeed("Context7 setup complete"); + + log.blank(); + for (const r of results) { + log.plain(` ${pc.bold(r.agent)}`); + const mcpIcon = + r.mcpStatus.startsWith("configured") || r.mcpStatus.startsWith("reconfigured") + ? pc.green("+") + : pc.dim("~"); + log.plain(` ${mcpIcon} MCP server ${r.mcpStatus}`); + log.plain(` ${pc.dim(r.mcpPath)}`); + const ruleIcon = r.ruleStatus === "installed" ? pc.green("+") : pc.dim("~"); + log.plain(` ${ruleIcon} Rule ${r.ruleStatus}`); + log.plain(` ${pc.dim(r.rulePath)}`); + logSkillStatus(r.skillStatus, r.skillPath); + } + log.blank(); + + trackEvent("setup", { agents, scope, authMode: auth.mode }); + trackEvent("install", { skills: ["/upstash/context7/context7-mcp"], ides: agents }); +} + +async function setupCliAgent( + agentName: SetupAgent, + scope: Scope, + downloadData: { files: Array<{ path: string; content: string }> } +): Promise<{ skillPath: string; skillStatus: string; rulePath: string; ruleStatus: string }> { + const agent = getAgent(agentName); + + const skillDir = + scope === "global" + ? agent.skill.dir("global") + : join(process.cwd(), agent.skill.dir("project")); + let skillStatus: string; + try { + const files = customizeSkillFilesForAgent(agentName, "find-docs", downloadData.files); + await installSkillFiles("find-docs", files, skillDir); + skillStatus = "installed"; + } catch (err) { + skillStatus = `failed: ${err instanceof Error ? err.message : String(err)}`; + } + const skillPath = join(skillDir, "find-docs"); + + let ruleStatus: string; + let rulePath: string; + try { + const result = await installRule(agentName, "cli", scope); + ruleStatus = result.status; + rulePath = result.path; + } catch (err) { + ruleStatus = `failed: ${err instanceof Error ? err.message : String(err)}`; + rulePath = ""; + } + + return { skillPath, skillStatus, rulePath, ruleStatus }; +} + +async function setupCli(options: SetupOptions): Promise { + await resolveCliAuth(options.apiKey); + + const scope: Scope = options.project ? "project" : "global"; + const agents = await resolveAgents(options, scope); + if (agents.length === 0) return; + + log.blank(); + const spinner = ora("Downloading find-docs skill...").start(); + + const downloadData = await downloadSkill("/upstash/context7", "find-docs"); + if (downloadData.error || downloadData.files.length === 0) { + spinner.fail(`Failed to download find-docs skill: ${downloadData.error || "no files"}`); + return; + } + + spinner.succeed("Downloaded find-docs skill"); + + const installSpinner = ora("Installing...").start(); + const results: Array<{ + agent: string; + skillPath: string; + skillStatus: string; + rulePath: string; + ruleStatus: string; + }> = []; + + for (const agentName of agents) { + const agentDef = getAgent(agentName); + installSpinner.text = `Setting up ${agentDef.displayName}...`; + const r = await setupCliAgent(agentName, scope, downloadData); + results.push({ agent: agentDef.displayName, ...r }); + } + + installSpinner.succeed("Context7 CLI setup complete"); + + log.blank(); + for (const r of results) { + log.plain(` ${pc.bold(r.agent)}`); + logSkillStatus(r.skillStatus, r.skillPath); + const ruleIcon = + r.ruleStatus === "installed" || r.ruleStatus === "updated" ? pc.green("+") : pc.dim("~"); + log.plain(` ${ruleIcon} Rule ${r.ruleStatus}`); + log.plain(` ${pc.dim(r.rulePath)}`); + } + log.blank(); + + trackEvent("setup", { mode: "cli" }); + trackEvent("install", { skills: ["/upstash/context7/find-docs"], ides: agents }); +} + +async function setupCommand(options: SetupOptions): Promise { + trackEvent("command", { name: "setup" }); + + try { + const mode = await resolveMode(options); + if (mode === "mcp") { + const scope: Scope = options.project ? "project" : "global"; + const agents = await resolveAgents(options, scope); + if (agents.length === 0) return; + await setupMcp(agents, options, scope); + } else { + await setupCli(options); + } + } catch (err) { + if (err instanceof Error && err.name === "ExitPromptError") process.exit(0); + throw err; + } +} diff --git a/packages/cli/src/commands/skill.ts b/packages/cli/src/commands/skill.ts new file mode 100644 index 0000000..72d6ef8 --- /dev/null +++ b/packages/cli/src/commands/skill.ts @@ -0,0 +1,1026 @@ +import { Command } from "commander"; +import pc from "picocolors"; +import ora from "ora"; +import { readdir, rm } from "fs/promises"; +import { join } from "path"; + +import { parseSkillInput } from "../utils/parse-input.js"; +import { + listProjectSkills, + searchSkills, + suggestSkills, + downloadSkill, + getSkill, +} from "../utils/api.js"; +import { log } from "../utils/logger.js"; +import { + promptForInstallTargets, + promptForSingleTarget, + getTargetDirs, + getTargetDirFromSelection, + getSelectedIdes, + hasExplicitIdeOption, +} from "../utils/ide.js"; +import { + checkboxWithHover, + terminalLink, + formatPopularity, + formatTrust, + formatInstallRange, + getTrustLabel, +} from "../utils/prompts.js"; +import { installSkillFiles, symlinkSkill } from "../utils/installer.js"; +import { assertSkillNameInRoot } from "../utils/skill-name.js"; +import { listSkillsFromGitHub, getSkillFromGitHub } from "../utils/github.js"; +import { trackEvent } from "../utils/tracking.js"; +import { registerGenerateCommand } from "./generate.js"; +import type { + Skill, + SkillSearchResult, + AddOptions, + ListOptions, + RemoveOptions, + SuggestOptions, + InstallTargets, + Scope, +} from "../types.js"; +import { + IDE_NAMES, + IDE_PATHS, + IDE_GLOBAL_PATHS, + UNIVERSAL_SKILLS_PATH, + UNIVERSAL_SKILLS_GLOBAL_PATH, + UNIVERSAL_AGENTS_LABEL, + VENDOR_SPECIFIC_AGENTS, +} from "../types.js"; +import { homedir } from "os"; +import { detectProjectDependencies } from "../utils/deps.js"; +import { loadTokens, isTokenExpired } from "../utils/auth.js"; + +const SKILL_HUB_DEPRECATION_WARNING = + "Warning: Skill commands are deprecated and will stop working in the next major release."; + +// TODO(deprecate-skills-phase-2): Delete this Skill Hub command tree once the +// deprecated `ctx7 skills ...` compatibility window closes. Do not remove the +// setup-installed Context7 skills with it. +function warnSkillHubDeprecated(): void { + console.error(pc.yellow(SKILL_HUB_DEPRECATION_WARNING)); + console.error(""); +} + +function logInstallSummary( + targets: InstallTargets, + targetDirs: string[], + skillNames: string[] +): void { + log.blank(); + const hasUniversal = targets.ides.some((ide) => ide === "universal"); + const vendorIdes = targets.ides.filter((ide) => ide !== "universal"); + + let dirIndex = 0; + if (hasUniversal && dirIndex < targetDirs.length) { + log.plain(`${pc.bold("Universal")} ${pc.dim(targetDirs[dirIndex])}`); + for (const name of skillNames) { + log.itemAdd(name); + } + dirIndex++; + } + + for (const ide of vendorIdes) { + if (dirIndex >= targetDirs.length) break; + log.plain(`${pc.bold(IDE_NAMES[ide])} ${pc.dim(targetDirs[dirIndex])}`); + for (const name of skillNames) { + log.itemAdd(name); + } + dirIndex++; + } + + log.blank(); +} + +export function registerSkillCommands(program: Command): void { + const skill = program + .command("skills", { hidden: true }) + .alias("skill") + .description("Manage AI coding skills") + .hook("preAction", () => { + warnSkillHubDeprecated(); + }); + + // Register generate subcommand + registerGenerateCommand(skill); + + skill + .command("install") + .alias("i") + .alias("add") + .argument("", "GitHub repository (/owner/repo)") + .argument("[skill]", "Specific skill name to install") + .option("--all", "Install all skills without prompting") + .option("--all-agents", "Install to all supported agent locations") + .option("-y, --yes", "Skip confirmation prompts") + .option("--global", "Install globally instead of current directory") + .option("--claude", "Claude Code (.claude/skills/)") + .option("--cursor", "Cursor (.cursor/skills/)") + .option("--universal", "Universal (.agents/skills/)") + .option("--antigravity", "Antigravity (.agent/skills/)") + .description("Install skills from a repository") + .action(async (project: string, skillName: string | undefined, options: AddOptions) => { + await installCommand(project, skillName, options); + }); + + skill + .command("search") + .alias("s") + .argument("", "Search keywords") + .description("Search for skills across all indexed repositories") + .action(async (keywords: string[]) => { + await searchCommand(keywords.join(" ")); + }); + + skill + .command("list") + .alias("ls") + .option("--json", "Output as JSON") + .option("--global", "List global skills") + .option("--claude", "Claude Code (.claude/skills/)") + .option("--cursor", "Cursor (.cursor/skills/)") + .option("--universal", "Universal (.agents/skills/)") + .option("--antigravity", "Antigravity (.agent/skills/)") + .description("List installed skills") + .action(async (options: ListOptions) => { + await listCommand(options); + }); + + skill + .command("remove") + .alias("rm") + .alias("delete") + .argument("", "Skill name to remove") + .option("--global", "Remove from global skills") + .option("--claude", "Claude Code (.claude/skills/)") + .option("--cursor", "Cursor (.cursor/skills/)") + .option("--universal", "Universal (.agents/skills/)") + .option("--antigravity", "Antigravity (.agent/skills/)") + .description("Remove an installed skill") + .action(async (name: string, options: RemoveOptions) => { + await removeCommand(name, options); + }); + + skill + .command("info") + .argument("", "GitHub repository (/owner/repo)") + .description("Show skills in a repository") + .action(async (project: string) => { + await infoCommand(project); + }); + + skill + .command("suggest") + .option("--global", "Install globally instead of current directory") + .option("--claude", "Claude Code (.claude/skills/)") + .option("--cursor", "Cursor (.cursor/skills/)") + .option("--universal", "Universal (.agents/skills/)") + .option("--antigravity", "Antigravity (.agent/skills/)") + .description("Suggest skills based on your project dependencies") + .action(async (options: SuggestOptions) => { + await suggestCommand(options); + }); +} + +export function registerSkillAliases(program: Command): void { + program + .command("si", { hidden: true }) + .argument("", "GitHub repository (/owner/repo)") + .argument("[skill]", "Specific skill name to install") + .option("--all", "Install all skills without prompting") + .option("--all-agents", "Install to all supported agent locations") + .option("-y, --yes", "Skip confirmation prompts") + .option("--global", "Install globally instead of current directory") + .option("--claude", "Claude Code (.claude/skills/)") + .option("--cursor", "Cursor (.cursor/skills/)") + .option("--universal", "Universal (.agents/skills/)") + .option("--antigravity", "Antigravity (.agent/skills/)") + .description("Install skills (alias for: skills install)") + .action(async (project: string, skillName: string | undefined, options: AddOptions) => { + warnSkillHubDeprecated(); + await installCommand(project, skillName, options); + }); + + program + .command("ss", { hidden: true }) + .argument("", "Search keywords") + .description("Search for skills (alias for: skills search)") + .action(async (keywords: string[]) => { + warnSkillHubDeprecated(); + await searchCommand(keywords.join(" ")); + }); + + program + .command("ssg", { hidden: true }) + .option("--global", "Install globally instead of current directory") + .option("--claude", "Claude Code (.claude/skills/)") + .option("--cursor", "Cursor (.cursor/skills/)") + .option("--universal", "Universal (.agents/skills/)") + .option("--antigravity", "Antigravity (.agent/skills/)") + .description("Suggest skills (alias for: skills suggest)") + .action(async (options: SuggestOptions) => { + warnSkillHubDeprecated(); + await suggestCommand(options); + }); +} + +async function installCommand( + input: string, + skillName: string | undefined, + options: AddOptions +): Promise { + trackEvent("command", { name: "install" }); + const parsed = parseSkillInput(input); + if (!parsed) { + log.error(`Invalid input format: ${input}`); + log.info(`Expected: /owner/repo or full GitHub URL`); + log.info(`Example: ctx7 skills install /anthropics/skills pdf`); + log.blank(); + return; + } + const repo = `/${parsed.owner}/${parsed.repo}`; + + log.blank(); + const spinner = ora(`Fetching skills from ${repo}...`).start(); + + let selectedSkills: (Skill & { project: string })[]; + + // When a specific skill name is provided, fetch only that skill + if (skillName) { + spinner.text = `Fetching skill: ${skillName}...`; + const skillData = await getSkill(repo, skillName); + + if (skillData.error || !skillData.name) { + if (skillData.error === "prompt_injection_detected") { + spinner.fail(pc.red(`Prompt injection detected in skill: ${skillName}`)); + log.warn("This skill contains potentially malicious content and cannot be installed."); + return; + } + + spinner.text = `Fetching skill from GitHub: ${skillName}...`; + const ghResult = await getSkillFromGitHub(repo, skillName); + if (ghResult.status === "repo_not_found") { + spinner.fail(pc.red(`Repository not found: ${repo}`)); + return; + } + if (ghResult.status !== "ok" || !ghResult.skill) { + spinner.fail(pc.red(`Skill not found: ${skillName}`)); + return; + } + + spinner.succeed(`Found skill: ${skillName}`); + selectedSkills = [ghResult.skill]; + } else { + spinner.succeed(`Found skill: ${skillName}`); + selectedSkills = [ + { + name: skillData.name, + description: skillData.description, + url: skillData.url, + project: repo, + }, + ]; + } + } else { + // Fetch all skills when no specific names provided + let data = await listProjectSkills(repo); + + if ((data.error || !data.skills || data.skills.length === 0) && !data.blockedSkillsCount) { + spinner.text = `Fetching skills from GitHub...`; + const ghResult = await listSkillsFromGitHub(repo); + if (ghResult.status === "repo_not_found") { + spinner.fail(pc.red(`Repository not found: ${repo}`)); + return; + } + if (ghResult.status === "ok" && ghResult.skills.length > 0) { + data = { project: repo, skills: ghResult.skills }; + } + } + + if (data.error && (!data.skills || data.skills.length === 0)) { + spinner.fail(pc.red(`Error: ${data.message || data.error}`)); + return; + } + + if (!data.skills || data.skills.length === 0) { + spinner.warn(pc.yellow(`No skills found in ${repo}`)); + return; + } + + const skillsWithRepo = data.skills + .map((s) => ({ ...s, project: repo })) + .sort((a, b) => (b.installCount ?? 0) - (a.installCount ?? 0)); + + spinner.succeed(`Found ${data.skills.length} skill(s)`); + + if (data.blockedSkillsCount && data.blockedSkillsCount > 0) { + log.blank(); + log.error( + `${data.blockedSkillsCount} skill(s) blocked due to prompt injection and not shown.` + ); + log.warn("Review other skills from this repository carefully before installing."); + } + + if (options.all || data.skills.length === 1) { + selectedSkills = skillsWithRepo; + } else { + const indexWidth = data.skills.length.toString().length; + const maxNameLen = Math.max(...data.skills.map((s) => s.name.length)); + const popularityColWidth = 13; + const choices = skillsWithRepo.map((s, index) => { + const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`); + const paddedName = s.name.padEnd(maxNameLen); + const popularity = formatPopularity(s.installCount) + " ".repeat(popularityColWidth - 4); + const trust = formatTrust(s.trustScore); + + const skillUrl = s.url || `https://github.com${s.project}`; + const skillLink = terminalLink(s.name, skillUrl, pc.white); + const repoLink = terminalLink(s.project, `https://github.com${s.project}`, pc.white); + const metadataLines = [ + pc.dim("─".repeat(50)), + "", + `${pc.yellow("Skill:")} ${skillLink}`, + `${pc.yellow("Repo:")} ${repoLink}`, + `${pc.yellow("Installs:")} ${pc.white(formatInstallRange(s.installCount))}`, + `${pc.yellow("Trust:")} ${s.trustScore !== undefined && s.trustScore >= 0 ? pc.white(s.trustScore.toFixed(1)) : pc.dim("-")}`, + `${pc.yellow("Description:")}`, + pc.white(s.description || "No description"), + ]; + + return { + name: `${indexStr} ${paddedName} ${popularity}${trust}`, + value: s, + description: metadataLines.join("\n"), + }; + }); + + log.blank(); + + const checkboxPrefixWidth = 3; + const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1); + const headerLine = + headerPad + pc.dim("Popularity".padEnd(popularityColWidth)) + pc.dim("Trust"); + + try { + selectedSkills = await checkboxWithHover({ + message: `Select skills to install:\n${headerLine}`, + choices, + pageSize: 15, + loop: false, + theme: { + style: { + message: (text: string, status: string) => { + if (status === "done") return pc.dim(text.split("\n")[0]); + return pc.bold(text); + }, + }, + }, + }); + } catch { + log.warn("Installation cancelled"); + return; + } + } + } + + if (selectedSkills.length === 0) { + log.warn("No skills selected"); + return; + } + + const targets = await promptForInstallTargets(options); + if (!targets) { + log.warn("Installation cancelled"); + return; + } + + const targetDirs = getTargetDirs(targets); + + const installSpinner = ora("Installing skills...").start(); + + let permissionError = false; + const failedDirs: Set = new Set(); + const installedSkills: string[] = []; + + for (const skill of selectedSkills) { + try { + installSpinner.text = `Downloading ${skill.name}...`; + const downloadData = await downloadSkill(skill.project, skill.name); + + if (downloadData.error) { + log.warn(`Failed to download ${skill.name}: ${downloadData.error}`); + continue; + } + + installSpinner.text = `Installing ${skill.name}...`; + + const [primaryDir, ...symlinkDirs] = targetDirs; + + try { + await installSkillFiles(skill.name, downloadData.files, primaryDir); + } catch (dirErr) { + const error = dirErr as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + permissionError = true; + failedDirs.add(primaryDir); + } + throw dirErr; + } + + const primarySkillDir = join(primaryDir, skill.name); + for (const targetDir of symlinkDirs) { + try { + await symlinkSkill(skill.name, primarySkillDir, targetDir); + } catch (dirErr) { + const error = dirErr as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + permissionError = true; + failedDirs.add(targetDir); + } + throw dirErr; + } + } + + installedSkills.push(`${skill.project}/${skill.name}`); + } catch (err) { + const error = err as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + continue; + } + const errMsg = err instanceof Error ? err.message : String(err); + log.warn(`Failed to install ${skill.name}: ${errMsg}`); + } + } + + if (permissionError) { + installSpinner.fail("Permission denied"); + log.blank(); + log.warn("Fix permissions with:"); + for (const dir of failedDirs) { + const parentDir = join(dir, ".."); + log.dim(` sudo chown -R $(whoami) "${parentDir}"`); + } + log.blank(); + return; + } + + installSpinner.succeed(`Installed ${installedSkills.length} skill(s)`); + trackEvent("install", { skills: installedSkills, ides: targets.ides }); + + const installedNames = selectedSkills.map((s) => s.name); + logInstallSummary(targets, targetDirs, installedNames); +} + +async function searchCommand(query: string): Promise { + trackEvent("command", { name: "search" }); + log.blank(); + const spinner = ora(`Searching for "${query}"...`).start(); + + let data; + try { + data = await searchSkills(query); + } catch (err) { + spinner.fail(pc.red(`Error: ${err instanceof Error ? err.message : String(err)}`)); + return; + } + + if (data.error) { + spinner.fail(pc.red(`Error: ${data.message || data.error}`)); + return; + } + + if (!data.results || data.results.length === 0) { + spinner.warn(pc.yellow(`No skills found matching "${query}"`)); + return; + } + + spinner.succeed(`Found ${data.results.length} skill(s)`); + trackEvent("search_query", { query, resultCount: data.results.length }); + log.blank(); + + const indexWidth = data.results.length.toString().length; + const nameWithRepo = (s: SkillSearchResult) => `${s.name} ${pc.dim(`(${s.project})`)}`; + const nameWithRepoLen = (s: SkillSearchResult) => `${s.name} (${s.project})`.length; + const maxNameLen = Math.max(...data.results.map(nameWithRepoLen)); + const popularityColWidth = 13; + const choices = data.results.map((s, index) => { + const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`); + const rawLen = nameWithRepoLen(s); + const displayName = nameWithRepo(s) + " ".repeat(maxNameLen - rawLen); + const popularity = formatPopularity(s.installCount) + " ".repeat(popularityColWidth - 4); + const trust = formatTrust(s.trustScore); + + const skillLink = terminalLink(s.name, s.url || `https://github.com${s.project}`, pc.white); + const repoLink = terminalLink(s.project, `https://github.com${s.project}`, pc.white); + const metadataLines = [ + pc.dim("─".repeat(50)), + "", + `${pc.yellow("Skill:")} ${skillLink}`, + `${pc.yellow("Repo:")} ${repoLink}`, + `${pc.yellow("Installs:")} ${pc.white(formatInstallRange(s.installCount))}`, + `${pc.yellow("Trust:")} ${s.trustScore !== undefined && s.trustScore >= 0 ? pc.white(s.trustScore.toFixed(1)) : pc.dim("-")}`, + `${pc.yellow("Description:")}`, + pc.white(s.description || "No description"), + ]; + + return { + name: `${indexStr} ${displayName} ${popularity}${trust}`, + value: s, + description: metadataLines.join("\n"), + }; + }); + + const checkboxPrefixWidth = 3; // "❯◯ " or " ◯ " + const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1); + const headerLine = headerPad + pc.dim("Popularity".padEnd(popularityColWidth)) + pc.dim("Trust"); + + let selectedSkills: SkillSearchResult[]; + try { + selectedSkills = await checkboxWithHover({ + message: `Select skills to install:\n${headerLine}`, + choices, + pageSize: 15, + loop: false, + theme: { + style: { + message: (text: string, status: string) => { + if (status === "done") return pc.dim(text.split("\n")[0]); + return pc.bold(text); + }, + }, + }, + }); + } catch { + log.warn("Installation cancelled"); + return; + } + + const uniqueSkills = selectedSkills; + + if (uniqueSkills.length === 0) { + log.warn("No skills selected"); + return; + } + + const targets = await promptForInstallTargets({}); + if (!targets) { + log.warn("Installation cancelled"); + return; + } + + const targetDirs = getTargetDirs(targets); + + const installSpinner = ora("Installing skills...").start(); + + let permissionError = false; + const failedDirs: Set = new Set(); + const installedSkills: string[] = []; + + for (const skill of uniqueSkills) { + try { + installSpinner.text = `Downloading ${skill.name}...`; + const downloadData = await downloadSkill(skill.project, skill.name); + + if (downloadData.error) { + log.warn(`Failed to download ${skill.name}: ${downloadData.error}`); + continue; + } + + installSpinner.text = `Installing ${skill.name}...`; + + const [primaryDir, ...symlinkDirs] = targetDirs; + + try { + await installSkillFiles(skill.name, downloadData.files, primaryDir); + } catch (dirErr) { + const error = dirErr as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + permissionError = true; + failedDirs.add(primaryDir); + } + throw dirErr; + } + + const primarySkillDir = join(primaryDir, skill.name); + for (const targetDir of symlinkDirs) { + try { + await symlinkSkill(skill.name, primarySkillDir, targetDir); + } catch (dirErr) { + const error = dirErr as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + permissionError = true; + failedDirs.add(targetDir); + } + throw dirErr; + } + } + + installedSkills.push(`${skill.project}/${skill.name}`); + } catch (err) { + const error = err as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + continue; + } + const errMsg = err instanceof Error ? err.message : String(err); + log.warn(`Failed to install ${skill.name}: ${errMsg}`); + } + } + + if (permissionError) { + installSpinner.fail("Permission denied"); + log.blank(); + log.warn("Fix permissions with:"); + for (const dir of failedDirs) { + const parentDir = join(dir, ".."); + log.dim(` sudo chown -R $(whoami) "${parentDir}"`); + } + log.blank(); + return; + } + + installSpinner.succeed(`Installed ${installedSkills.length} skill(s)`); + trackEvent("install", { skills: installedSkills, ides: targets.ides }); + + const installedNames = uniqueSkills.map((s) => s.name); + logInstallSummary(targets, targetDirs, installedNames); +} + +async function listCommand(options: ListOptions): Promise { + trackEvent("command", { name: "list" }); + const scope: Scope = options.global ? "global" : "project"; + const baseDir = scope === "global" ? homedir() : process.cwd(); + + const results: { + label: string; + displayPath: string; + dir: string; + source: string; + skills: string[]; + }[] = []; + + // Helper to scan a skills directory + async function scanDir(dir: string): Promise { + try { + const entries = await readdir(dir, { withFileTypes: true }); + return entries.filter((e) => e.isDirectory() || e.isSymbolicLink()).map((e) => e.name); + } catch { + return []; + } + } + + if (hasExplicitIdeOption(options)) { + // Explicit flag mode — check the specific IDE paths + const ides = getSelectedIdes(options); + for (const ide of ides) { + const dir = + ide === "universal" + ? join(baseDir, scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH) + : join(baseDir, (scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS)[ide]); + const label = ide === "universal" ? UNIVERSAL_AGENTS_LABEL : IDE_NAMES[ide]; + const skills = await scanDir(dir); + if (skills.length > 0) { + results.push({ label, displayPath: dir, dir, source: ide, skills }); + } + } + } else { + // Default: check universal + vendor-specific + const universalPath = scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH; + const universalDir = join(baseDir, universalPath); + const universalSkills = await scanDir(universalDir); + if (universalSkills.length > 0) { + results.push({ + label: UNIVERSAL_AGENTS_LABEL, + displayPath: universalPath, + dir: universalDir, + source: "universal", + skills: universalSkills, + }); + } + + for (const ide of VENDOR_SPECIFIC_AGENTS) { + const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS; + const dir = join(baseDir, pathMap[ide]); + const skills = await scanDir(dir); + if (skills.length > 0) { + results.push({ + label: IDE_NAMES[ide], + displayPath: pathMap[ide], + dir, + source: ide, + skills, + }); + } + } + } + + if (options.json) { + const skills = results.flatMap((result) => + result.skills.map((name) => ({ + name, + path: join(result.dir, name), + source: result.source, + })) + ); + + console.log(JSON.stringify({ skills }, null, 2)); + return; + } + + if (results.length === 0) { + log.warn("No skills installed"); + return; + } + + log.blank(); + + for (const { label, displayPath, skills } of results) { + log.plain(`${pc.bold(label)} ${pc.dim(displayPath)}`); + for (const skill of skills) { + log.plain(` ${pc.green(skill)}`); + } + log.blank(); + } +} + +async function removeCommand(name: string, options: RemoveOptions): Promise { + trackEvent("command", { name: "remove" }); + const target = await promptForSingleTarget(options); + if (!target) { + log.warn("Cancelled"); + return; + } + + const skillsDir = getTargetDirFromSelection(target.ide, target.scope); + let skillPath: string; + try { + skillPath = assertSkillNameInRoot(skillsDir, name); + } catch { + log.error(`Invalid skill name: ${name}`); + return; + } + + try { + await rm(skillPath, { recursive: true }); + log.success(`Removed skill: ${name}`); + } catch (err) { + const error = err as NodeJS.ErrnoException; + if (error.code === "ENOENT") { + log.error(`Skill not found: ${name}`); + } else if (error.code === "EACCES" || error.code === "EPERM") { + log.error(`Permission denied. Try: sudo rm -rf "${skillPath}"`); + } else { + log.error(`Failed to remove skill: ${error.message}`); + } + } +} + +async function infoCommand(input: string): Promise { + trackEvent("command", { name: "info" }); + const parsed = parseSkillInput(input); + if (!parsed) { + log.blank(); + log.error(`Invalid input format: ${input}`); + log.info(`Expected: /owner/repo or full GitHub URL`); + log.blank(); + return; + } + const repo = `/${parsed.owner}/${parsed.repo}`; + + log.blank(); + const spinner = ora(`Fetching skills from ${repo}...`).start(); + + const data = await listProjectSkills(repo); + + if (data.error) { + spinner.fail(pc.red(`Error: ${data.message || data.error}`)); + return; + } + + if (!data.skills || data.skills.length === 0) { + spinner.warn(pc.yellow(`No skills found in ${repo}`)); + return; + } + + spinner.succeed(`Found ${data.skills.length} skill(s)`); + + log.blank(); + for (const skill of data.skills) { + log.item(skill.name); + log.dim(` ${skill.description || "No description"}`); + log.dim(` URL: ${skill.url}`); + log.blank(); + } + + log.plain( + `${pc.bold("Quick commands:")}\n` + + ` Install all: ${pc.cyan(`ctx7 skills install ${repo} --all`)}\n` + + ` Install one: ${pc.cyan(`ctx7 skills install ${repo} ${data.skills[0]?.name}`)}\n` + ); +} + +async function suggestCommand(options: SuggestOptions): Promise { + trackEvent("command", { name: "suggest" }); + log.blank(); + + // Step 1: Detect dependencies + const scanSpinner = ora("Scanning project dependencies...").start(); + const deps = await detectProjectDependencies(process.cwd()); + + if (deps.length === 0) { + scanSpinner.warn(pc.yellow("No dependencies detected")); + log.info(`Try ${pc.cyan("ctx7 skills search ")} to search manually`); + return; + } + + scanSpinner.succeed(`Found ${deps.length} dependencies`); + + // Step 2: Single API call to backend + const searchSpinner = ora("Finding matching skills...").start(); + + const tokens = loadTokens(); + const accessToken = tokens && !isTokenExpired(tokens) ? tokens.access_token : undefined; + + let data; + try { + data = await suggestSkills(deps, accessToken); + } catch { + searchSpinner.fail(pc.red("Failed to connect to Context7")); + return; + } + + if (data.error) { + searchSpinner.fail(pc.red(`Error: ${data.message || data.error}`)); + return; + } + + const skills = data.skills; + + if (skills.length === 0) { + searchSpinner.warn(pc.yellow("No matching skills found for your dependencies")); + return; + } + + searchSpinner.succeed(`Found ${skills.length} relevant skill(s)`); + trackEvent("suggest_results", { depCount: deps.length, skillCount: skills.length }); + log.blank(); + + const nameWithRepo = (s: SkillSearchResult) => `${s.name} ${pc.dim(`(${s.project})`)}`; + const nameWithRepoLen = (s: SkillSearchResult) => `${s.name} (${s.project})`.length; + const maxNameLen = Math.max(...skills.map(nameWithRepoLen)); + const popularityColWidth = 13; + const trustColWidth = 8; + const maxMatchedLen = Math.max(...skills.map((s) => s.matchedDep.length)); + const indexWidth = skills.length.toString().length; + + const choices = skills.map((s, index) => { + const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`); + const rawLen = nameWithRepoLen(s); + const displayName = nameWithRepo(s) + " ".repeat(maxNameLen - rawLen); + const popularity = formatPopularity(s.installCount) + " ".repeat(popularityColWidth - 4); + const trustLabel = getTrustLabel(s.trustScore); + const trust = formatTrust(s.trustScore) + " ".repeat(trustColWidth - trustLabel.length); + const matched = pc.yellow(s.matchedDep.padEnd(maxMatchedLen)); + + const skillLink = terminalLink(s.name, s.url || `https://github.com${s.project}`, pc.white); + const repoLink = terminalLink(s.project, `https://github.com${s.project}`, pc.white); + const metadataLines = [ + pc.dim("─".repeat(50)), + "", + `${pc.yellow("Skill:")} ${skillLink}`, + `${pc.yellow("Repo:")} ${repoLink}`, + `${pc.yellow("Installs:")} ${pc.white(formatInstallRange(s.installCount))}`, + `${pc.yellow("Trust:")} ${s.trustScore !== undefined && s.trustScore >= 0 ? pc.white(s.trustScore.toFixed(1)) : pc.dim("-")}`, + `${pc.yellow("Relevant:")} ${pc.white(s.matchedDep)}`, + `${pc.yellow("Description:")}`, + pc.white(s.description || "No description"), + ]; + + return { + name: `${indexStr} ${displayName} ${popularity}${trust}${matched}`, + value: s, + description: metadataLines.join("\n"), + }; + }); + + const checkboxPrefixWidth = 3; // "❯◯ " or " ◯ " + const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1); + const headerLine = + headerPad + + pc.dim("Popularity".padEnd(popularityColWidth)) + + pc.dim("Trust".padEnd(trustColWidth)) + + pc.dim("Relevant"); + + let selectedSkills: SkillSearchResult[]; + try { + selectedSkills = await checkboxWithHover({ + message: `Select skills to install:\n${headerLine}`, + choices, + pageSize: 15, + loop: false, + theme: { + style: { + message: (text: string, status: string) => { + if (status === "done") return pc.dim(text.split("\n")[0]); + return pc.bold(text); + }, + }, + }, + }); + } catch { + log.warn("Installation cancelled"); + return; + } + + if (selectedSkills.length === 0) { + log.warn("No skills selected"); + return; + } + + // Step 4: Install (same pattern as searchCommand) + const targets = await promptForInstallTargets(options); + if (!targets) { + log.warn("Installation cancelled"); + return; + } + + const targetDirs = getTargetDirs(targets); + const installSpinner = ora("Installing skills...").start(); + + let permissionError = false; + const failedDirs: Set = new Set(); + const installedSkills: string[] = []; + + for (const skill of selectedSkills) { + try { + installSpinner.text = `Downloading ${skill.name}...`; + const downloadData = await downloadSkill(skill.project, skill.name); + + if (downloadData.error) { + log.warn(`Failed to download ${skill.name}: ${downloadData.error}`); + continue; + } + + installSpinner.text = `Installing ${skill.name}...`; + + const [primaryDir, ...symlinkDirs] = targetDirs; + + try { + await installSkillFiles(skill.name, downloadData.files, primaryDir); + } catch (dirErr) { + const error = dirErr as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + permissionError = true; + failedDirs.add(primaryDir); + } + throw dirErr; + } + + const primarySkillDir = join(primaryDir, skill.name); + for (const targetDir of symlinkDirs) { + try { + await symlinkSkill(skill.name, primarySkillDir, targetDir); + } catch (dirErr) { + const error = dirErr as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + permissionError = true; + failedDirs.add(targetDir); + } + throw dirErr; + } + } + + installedSkills.push(`${skill.project}/${skill.name}`); + } catch (err) { + const error = err as NodeJS.ErrnoException; + if (error.code === "EACCES" || error.code === "EPERM") { + continue; + } + const errMsg = err instanceof Error ? err.message : String(err); + log.warn(`Failed to install ${skill.name}: ${errMsg}`); + } + } + + if (permissionError) { + installSpinner.fail("Permission denied"); + log.blank(); + log.warn("Fix permissions with:"); + for (const dir of failedDirs) { + const parentDir = join(dir, ".."); + log.dim(` sudo chown -R $(whoami) "${parentDir}"`); + } + log.blank(); + return; + } + + installSpinner.succeed(`Installed ${installedSkills.length} skill(s)`); + trackEvent("suggest_install", { skills: installedSkills, ides: targets.ides }); + + const installedNames = selectedSkills.map((s) => s.name); + logInstallSummary(targets, targetDirs, installedNames); +} diff --git a/packages/cli/src/commands/upgrade.ts b/packages/cli/src/commands/upgrade.ts new file mode 100644 index 0000000..b0b870c --- /dev/null +++ b/packages/cli/src/commands/upgrade.ts @@ -0,0 +1,190 @@ +import { confirm } from "@inquirer/prompts"; +import { spawn } from "child_process"; +import { Command } from "commander"; +import pc from "picocolors"; +import { VERSION } from "../constants.js"; +import { log } from "../utils/logger.js"; +import { trackEvent } from "../utils/tracking.js"; +import { + checkForUpdates, + getUpgradePlan, + markUpdateNotificationShown, + shouldShowUpdateNotification, + shouldSkipUpdateNotifier, + type UpgradePlan, +} from "../utils/update-check.js"; + +interface UpgradeOptions { + yes?: boolean; + check?: boolean; +} + +export function registerUpgradeCommand(program: Command): void { + program + .command("upgrade") + .description("Check for a newer ctx7 version and upgrade when possible") + .option("-y, --yes", "Run the suggested upgrade command without prompting") + .option("--check", "Only check for updates without running the upgrade command") + .action(async (options: UpgradeOptions) => { + await upgradeCommand(options); + }); +} + +function runCommand(command: string, args: string[]): Promise { + return new Promise((resolve, reject) => { + const child = spawn(command, args, { + stdio: "inherit", + shell: process.platform === "win32", + }); + + child.on("error", reject); + child.on("close", (code) => resolve(code)); + }); +} + +export async function runUpgradePlan(plan: UpgradePlan): Promise { + return runCommand(plan.command, plan.args); +} + +function showUpgradeFailureHelp(plan: UpgradePlan): void { + log.info(`Try rerunning: ${pc.cyan(plan.displayCommand)}`); + + const isGlobalNpmInstall = + (plan.installMethod === "npm-global" || plan.installMethod === "unknown") && + plan.command === "npm" && + plan.args.includes("-g"); + const isGlobalAltInstall = + (plan.installMethod === "pnpm-global" || plan.installMethod === "bun-global") && + plan.args.includes("-g"); + + if (isGlobalNpmInstall) { + log.dim( + "If this failed due to permissions, your global npm directory may require elevated privileges on this machine." + ); + } else if (isGlobalAltInstall) { + log.dim( + "If this failed due to permissions, your global package manager install location may require additional privileges on this machine." + ); + } +} + +export async function maybeShowUpgradeNotice( + options: { + actionName?: string; + argv?: string[]; + isInteractive?: boolean; + } = {} +): Promise { + const actionName = options.actionName ?? ""; + const argv = options.argv ?? process.argv; + const isInteractive = + options.isInteractive ?? Boolean(process.stdout.isTTY && process.stdin.isTTY); + + if (!isInteractive || shouldSkipUpdateNotifier(argv) || actionName === "upgrade") { + return; + } + + const info = await checkForUpdates(); + if (!info || !info.updateAvailable || !(await shouldShowUpdateNotification(info))) { + return; + } + + log.blank(); + if (info.upgradePlan.needsExplicitVersion) { + log.box([ + `${pc.white(pc.bold("Update available:"))} ${pc.green(pc.bold(`v${info.currentVersion}`))} ${pc.dim("->")} ${pc.green(pc.bold(`v${info.latestVersion}`))}`, + `${pc.white("Use")} ${pc.yellow(pc.bold(info.upgradePlan.displayCommand))} ${pc.white("to run the latest version")}`, + ]); + await markUpdateNotificationShown(info.latestVersion); + log.blank(); + return; + } + + if (!info.upgradePlan.canRun) { + log.box([ + `${pc.white(pc.bold("Update available:"))} ${pc.green(pc.bold(`v${info.currentVersion}`))} ${pc.dim("->")} ${pc.green(pc.bold(`v${info.latestVersion}`))}`, + `${pc.white("Run")} ${pc.yellow(pc.bold("ctx7 upgrade"))} ${pc.white("for update steps")}`, + `${pc.white("Or run")} ${pc.yellow(info.upgradePlan.displayCommand)}`, + ]); + await markUpdateNotificationShown(info.latestVersion); + log.blank(); + return; + } + + log.box([ + `${pc.white(pc.bold("Update available:"))} ${pc.green(pc.bold(`v${info.currentVersion}`))} ${pc.dim("->")} ${pc.green(pc.bold(`v${info.latestVersion}`))}`, + `${pc.white("Run")} ${pc.yellow(pc.bold("ctx7 upgrade"))} ${pc.white("to update now")}`, + `${pc.white("Or run")} ${pc.yellow(info.upgradePlan.displayCommand)}`, + ]); + await markUpdateNotificationShown(info.latestVersion); + log.blank(); +} + +async function upgradeCommand(options: UpgradeOptions): Promise { + trackEvent("command", { name: "upgrade" }); + + const info = await checkForUpdates({ force: true }); + const plan = info?.upgradePlan ?? getUpgradePlan(); + + if (!info) { + log.warn("Couldn't check for updates right now."); + log.info(`Try again later or run ${pc.cyan(plan.displayCommand)} manually.`); + return; + } + + if (!info.updateAvailable) { + log.success(`ctx7 is up to date (${pc.bold(`v${VERSION}`)})`); + return; + } + + log.blank(); + log.info( + `Update available: ${pc.bold(`v${info.currentVersion}`)} ${pc.dim("->")} ${pc.bold(`v${info.latestVersion}`)}` + ); + + if (plan.needsExplicitVersion) { + log.info(`You're using an ephemeral runner (${plan.installMethod}).`); + log.info(`Use ${pc.cyan(plan.displayCommand)} to run the latest version immediately.`); + log.info(`Or install globally with ${pc.cyan("npm install -g ctx7@latest")}.`); + return; + } + + if (!plan.canRun) { + log.info(`Run ${pc.cyan(plan.displayCommand)} to update your installed version.`); + return; + } + + log.info(`Upgrade command: ${pc.cyan(plan.displayCommand)}`); + + if (options.check) { + return; + } + + let shouldRun = options.yes ?? false; + if (!shouldRun && process.stdout.isTTY) { + shouldRun = await confirm({ + message: `Run ${plan.displayCommand} now?`, + default: true, + }); + } + + if (!shouldRun) { + log.dim("Upgrade skipped."); + return; + } + + log.blank(); + const exitCode = await runUpgradePlan(plan); + + if (exitCode === 0) { + log.blank(); + log.success("Upgrade complete."); + log.info(`Run ${pc.cyan("ctx7 --version")} to verify the installed version.`); + return; + } + + log.blank(); + log.error(`Upgrade command exited with code ${exitCode ?? "unknown"}.`); + showUpgradeFailureHelp(plan); + process.exitCode = 1; +} diff --git a/packages/cli/src/constants.ts b/packages/cli/src/constants.ts new file mode 100644 index 0000000..4aa356e --- /dev/null +++ b/packages/cli/src/constants.ts @@ -0,0 +1,10 @@ +import { readFileSync } from "fs"; +import { fileURLToPath } from "url"; +import { dirname, join } from "path"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8")); + +export const VERSION: string = pkg.version; +export const NAME: string = pkg.name; +export const CLI_CLIENT_ID = "2veBSofhicRBguUT"; diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts new file mode 100644 index 0000000..2544b9f --- /dev/null +++ b/packages/cli/src/index.ts @@ -0,0 +1,83 @@ +import { Command } from "commander"; +import pc from "picocolors"; +import figlet from "figlet"; +import { registerSkillCommands, registerSkillAliases } from "./commands/skill.js"; +import { registerAuthCommands, setAuthBaseUrl } from "./commands/auth.js"; +import { registerSetupCommand } from "./commands/setup.js"; +import { registerRemoveCommand } from "./commands/remove.js"; +import { registerDocsCommands } from "./commands/docs.js"; +import { maybeShowUpgradeNotice, registerUpgradeCommand } from "./commands/upgrade.js"; +import { setBaseUrl } from "./utils/api.js"; +import { VERSION } from "./constants.js"; + +const brand = { + primary: pc.green, + dim: pc.dim, +}; + +const program = new Command(); + +program + .name("ctx7") + .description("Context7 CLI - Fetch documentation context and configure Context7") + .version(VERSION, "-v, --version") + .option("--base-url ") + .hook("preAction", (thisCommand) => { + const opts = thisCommand.opts(); + if (opts.baseUrl) { + setBaseUrl(opts.baseUrl); + setAuthBaseUrl(opts.baseUrl); + } + }) + .hook("preAction", async (_thisCommand, actionCommand) => { + await maybeShowUpgradeNotice({ + actionName: actionCommand.name(), + argv: process.argv, + }); + }) + .addHelpText( + "after", + ` +Examples: + ${brand.dim("# Configure Context7 for your coding agent")} + ${brand.primary("npx ctx7 setup")} + ${brand.primary("npx ctx7 setup --mcp")} + ${brand.primary("npx ctx7 setup --cli")} + + ${brand.dim("# Remove Context7 setup")} + ${brand.primary("npx ctx7 remove --cursor")} + ${brand.primary("npx ctx7 remove --cursor --all")} + ${brand.primary("npx ctx7 remove --cursor --cli")} + ${brand.primary("npx ctx7 remove --claude --mcp")} + + ${brand.dim("# Query library documentation")} + ${brand.primary('npx ctx7 library react "how to use hooks"')} + ${brand.primary('npx ctx7 docs /facebook/react "useEffect examples"')} +` + ); + +registerSkillCommands(program); +registerSkillAliases(program); +registerAuthCommands(program); +registerSetupCommand(program); +registerRemoveCommand(program); +registerDocsCommands(program); +registerUpgradeCommand(program); + +program.action(() => { + console.log(""); + const banner = figlet.textSync("Context7", { font: "ANSI Shadow" }); + console.log(brand.primary(banner)); + console.log(brand.dim(" Documentation context for AI coding agents")); + console.log(""); + + console.log(" Quick start:"); + console.log(` ${brand.primary("npx ctx7 setup")}`); + console.log(` ${brand.primary('npx ctx7 docs /facebook/react "useEffect examples"')}`); + console.log(""); + + console.log(` Run ${brand.primary("npx ctx7 --help")} for all commands and options`); + console.log(""); +}); + +await program.parseAsync(); diff --git a/packages/cli/src/setup/agents.ts b/packages/cli/src/setup/agents.ts new file mode 100644 index 0000000..e5cd1bc --- /dev/null +++ b/packages/cli/src/setup/agents.ts @@ -0,0 +1,303 @@ +import { access } from "fs/promises"; +import { join } from "path"; +import { homedir } from "os"; + +export type SetupAgent = "claude" | "cursor" | "opencode" | "codex" | "antigravity" | "gemini"; +export type AuthMode = "oauth" | "api-key"; +export type Transport = "http" | "stdio"; + +export interface AuthOptions { + mode: AuthMode; + apiKey?: string; +} + +export const SETUP_AGENT_NAMES: Record = { + claude: "Claude Code", + cursor: "Cursor", + opencode: "OpenCode", + codex: "Codex", + antigravity: "Antigravity", + gemini: "Gemini CLI", +}; + +export const AUTH_MODE_LABELS: Record = { + oauth: "OAuth", + "api-key": "API Key", +}; + +const MCP_BASE_URL = "https://mcp.context7.com"; +export const STDIO_PACKAGE = "@upstash/context7-mcp"; + +function stdioArgs(auth: AuthOptions): string[] { + const args = ["-y", STDIO_PACKAGE]; + if (auth.mode === "api-key" && auth.apiKey) { + args.push("--api-key", auth.apiKey); + } + return args; +} + +function stdioEntry(auth: AuthOptions): Record { + return { command: "npx", args: stdioArgs(auth) }; +} + +function claudeConfigDir(): string { + return process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"); +} + +function claudeGlobalMcpPath(): string { + if (process.env.CLAUDE_CONFIG_DIR) { + return join(claudeConfigDir(), ".claude.json"); + } + return join(homedir(), ".claude.json"); +} + +export type RuleType = + | { + kind: "file"; + dir: (scope: "project" | "global") => string; + filename: string; + } + | { kind: "append"; file: (scope: "project" | "global") => string; sectionMarker: string }; + +export interface AgentConfig { + name: SetupAgent; + displayName: string; + mcp: { + projectPaths: string[]; + globalPaths: string[]; + configKey: string; + buildEntry: (auth: AuthOptions, transport: Transport) => Record; + }; + rule: RuleType; + skill: { + name: string; + dir: (scope: "project" | "global") => string; + }; + detect: { + projectPaths: string[]; + globalPaths: string[]; + }; +} + +function mcpUrl(auth: AuthOptions): string { + return auth.mode === "oauth" ? `${MCP_BASE_URL}/mcp/oauth` : `${MCP_BASE_URL}/mcp`; +} + +function withHeaders(base: Record, auth: AuthOptions): Record { + if (auth.mode === "api-key" && auth.apiKey) { + return { ...base, headers: { CONTEXT7_API_KEY: auth.apiKey } }; + } + return base; +} + +const agents: Record = { + claude: { + name: "claude", + displayName: "Claude Code", + mcp: { + projectPaths: [".mcp.json"], + get globalPaths() { + return [claudeGlobalMcpPath()]; + }, + configKey: "mcpServers", + buildEntry: (auth, transport) => + transport === "stdio" + ? stdioEntry(auth) + : withHeaders({ type: "http", url: mcpUrl(auth) }, auth), + }, + rule: { + kind: "file", + dir: (scope) => + scope === "global" ? join(claudeConfigDir(), "rules") : join(".claude", "rules"), + filename: "context7.md", + }, + skill: { + name: "context7-mcp", + dir: (scope) => + scope === "global" ? join(claudeConfigDir(), "skills") : join(".claude", "skills"), + }, + detect: { + projectPaths: [".mcp.json", ".claude"], + get globalPaths() { + return [claudeConfigDir()]; + }, + }, + }, + + cursor: { + name: "cursor", + displayName: "Cursor", + mcp: { + projectPaths: [join(".cursor", "mcp.json")], + globalPaths: [join(homedir(), ".cursor", "mcp.json")], + configKey: "mcpServers", + buildEntry: (auth, transport) => + transport === "stdio" ? stdioEntry(auth) : withHeaders({ url: mcpUrl(auth) }, auth), + }, + rule: { + kind: "file", + dir: (scope) => + scope === "global" ? join(homedir(), ".cursor", "rules") : join(".cursor", "rules"), + filename: "context7.mdc", + }, + skill: { + name: "context7-mcp", + dir: (scope) => + scope === "global" ? join(homedir(), ".cursor", "skills") : join(".cursor", "skills"), + }, + detect: { + projectPaths: [".cursor"], + globalPaths: [join(homedir(), ".cursor")], + }, + }, + + opencode: { + name: "opencode", + displayName: "OpenCode", + mcp: { + projectPaths: ["opencode.json", "opencode.jsonc", ".opencode.json", ".opencode.jsonc"], + globalPaths: [ + join(homedir(), ".config", "opencode", "opencode.json"), + join(homedir(), ".config", "opencode", "opencode.jsonc"), + join(homedir(), ".config", "opencode", ".opencode.json"), + join(homedir(), ".config", "opencode", ".opencode.jsonc"), + ], + configKey: "mcp", + buildEntry: (auth, transport) => + transport === "stdio" + ? { type: "local", command: ["npx", ...stdioArgs(auth)], enabled: true } + : withHeaders({ type: "remote", url: mcpUrl(auth), enabled: true }, auth), + }, + rule: { + kind: "append", + file: (scope) => + scope === "global" ? join(homedir(), ".config", "opencode", "AGENTS.md") : "AGENTS.md", + sectionMarker: "", + }, + skill: { + name: "context7-mcp", + dir: (scope) => + scope === "global" ? join(homedir(), ".agents", "skills") : join(".agents", "skills"), + }, + detect: { + projectPaths: ["opencode.json", "opencode.jsonc", ".opencode.json", ".opencode.jsonc"], + globalPaths: [join(homedir(), ".config", "opencode")], + }, + }, + + codex: { + name: "codex", + displayName: "Codex", + mcp: { + projectPaths: [join(".codex", "config.toml")], + globalPaths: [join(homedir(), ".codex", "config.toml")], + configKey: "mcp_servers", + buildEntry: (auth, transport) => + transport === "stdio" + ? stdioEntry(auth) + : withHeaders({ type: "http", url: mcpUrl(auth) }, auth), + }, + rule: { + kind: "append", + file: (scope) => (scope === "global" ? join(homedir(), ".codex", "AGENTS.md") : "AGENTS.md"), + sectionMarker: "", + }, + skill: { + name: "context7-mcp", + dir: (scope) => + scope === "global" ? join(homedir(), ".agents", "skills") : join(".agents", "skills"), + }, + detect: { + projectPaths: [".codex"], + globalPaths: [join(homedir(), ".codex")], + }, + }, + + // Antigravity is built on Gemini infrastructure and shares ~/.gemini/. Per + // the official Codelabs guide, Antigravity 2.0/IDE/CLI read MCP servers from + // ~/.gemini/config/mcp_config.json globally; there is no project-level MCP + // config, so projectPaths is empty and setupAgent falls back to global. + antigravity: { + name: "antigravity", + displayName: "Antigravity", + mcp: { + projectPaths: [], + globalPaths: [join(homedir(), ".gemini", "config", "mcp_config.json")], + configKey: "mcpServers", + buildEntry: (auth, transport) => + transport === "stdio" ? stdioEntry(auth) : withHeaders({ serverUrl: mcpUrl(auth) }, auth), + }, + rule: { + kind: "append", + file: (scope) => (scope === "global" ? join(homedir(), ".gemini", "GEMINI.md") : "GEMINI.md"), + sectionMarker: "", + }, + skill: { + name: "context7-mcp", + dir: (scope) => + scope === "global" ? join(homedir(), ".agent", "skills") : join(".agent", "skills"), + }, + detect: { + projectPaths: [".agent"], + globalPaths: [join(homedir(), ".gemini", "antigravity"), join(homedir(), ".agent")], + }, + }, + + gemini: { + name: "gemini", + displayName: "Gemini CLI", + mcp: { + projectPaths: [join(".gemini", "settings.json")], + globalPaths: [join(homedir(), ".gemini", "settings.json")], + configKey: "mcpServers", + buildEntry: (auth, transport) => + transport === "stdio" ? stdioEntry(auth) : withHeaders({ httpUrl: mcpUrl(auth) }, auth), + }, + rule: { + kind: "append", + file: (scope) => (scope === "global" ? join(homedir(), ".gemini", "GEMINI.md") : "GEMINI.md"), + sectionMarker: "", + }, + skill: { + name: "context7-mcp", + dir: (scope) => + scope === "global" ? join(homedir(), ".gemini", "skills") : join(".gemini", "skills"), + }, + detect: { + projectPaths: [".gemini"], + globalPaths: [join(homedir(), ".gemini")], + }, + }, +}; + +export function getAgent(name: SetupAgent): AgentConfig { + return agents[name]; +} + +export const ALL_AGENT_NAMES: SetupAgent[] = Object.keys(agents) as SetupAgent[]; + +async function pathExists(p: string): Promise { + try { + await access(p); + return true; + } catch { + return false; + } +} + +export async function detectAgents(scope: "project" | "global"): Promise { + const detected: SetupAgent[] = []; + + for (const agent of Object.values(agents)) { + const paths = scope === "global" ? agent.detect.globalPaths : agent.detect.projectPaths; + for (const p of paths) { + const fullPath = scope === "global" ? p : join(process.cwd(), p); + if (await pathExists(fullPath)) { + detected.push(agent.name); + break; + } + } + } + + return detected; +} diff --git a/packages/cli/src/setup/mcp-writer.ts b/packages/cli/src/setup/mcp-writer.ts new file mode 100644 index 0000000..1c9ddf1 --- /dev/null +++ b/packages/cli/src/setup/mcp-writer.ts @@ -0,0 +1,340 @@ +import { access, readFile, writeFile, mkdir } from "fs/promises"; +import { dirname } from "path"; +import { STDIO_PACKAGE } from "./agents.js"; + +function stripJsonComments(text: string): string { + let result = ""; + let i = 0; + while (i < text.length) { + if (text[i] === '"') { + const start = i++; + while (i < text.length && text[i] !== '"') { + if (text[i] === "\\") i++; + i++; + } + result += text.slice(start, ++i); + } else if (text[i] === "/" && text[i + 1] === "/") { + i += 2; + while (i < text.length && text[i] !== "\n") i++; + } else if (text[i] === "/" && text[i + 1] === "*") { + i += 2; + while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++; + i += 2; + } else { + result += text[i++]; + } + } + return result; +} + +export async function readJsonConfig(filePath: string): Promise> { + let raw: string; + try { + raw = await readFile(filePath, "utf-8"); + } catch { + return {}; + } + + raw = raw.trim(); + if (!raw) return {}; + + return JSON.parse(stripJsonComments(raw)) as Record; +} + +export function mergeServerEntry( + existing: Record, + configKey: string, + serverName: string, + entry: Record +): { config: Record; alreadyExists: boolean } { + const section = (existing[configKey] as Record | undefined) ?? {}; + const alreadyExists = serverName in section; + + return { + config: { + ...existing, + [configKey]: { + ...section, + [serverName]: entry, + }, + }, + alreadyExists, + }; +} + +export function removeServerEntry( + existing: Record, + configKey: string, + serverName: string +): { config: Record; removed: boolean } { + const section = existing[configKey]; + if (!section || typeof section !== "object" || Array.isArray(section)) { + return { config: existing, removed: false }; + } + + const current = section as Record; + if (!(serverName in current)) { + return { config: existing, removed: false }; + } + + const rest = Object.fromEntries(Object.entries(current).filter(([key]) => key !== serverName)); + const next = { ...existing }; + + if (Object.keys(rest).length === 0) { + delete next[configKey]; + } else { + next[configKey] = rest; + } + + return { config: next, removed: true }; +} + +export async function resolveMcpPath(candidates: string[]): Promise { + for (const candidate of candidates) { + try { + await access(candidate); + return candidate; + } catch {} + } + return candidates[0]; +} + +export async function writeJsonConfig( + filePath: string, + config: Record +): Promise { + await mkdir(dirname(filePath), { recursive: true }); + await writeFile(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8"); +} + +export async function readTomlServerExists(filePath: string, serverName: string): Promise { + try { + const raw = await readFile(filePath, "utf-8"); + return raw.includes(`[mcp_servers.${serverName}]`); + } catch { + return false; + } +} + +/** + * Reads the top-level `[mcp_servers.]` block from a TOML config + * file and parses its key-value lines into a JS object. Handles string and + * array values (TOML array syntax is JSON-compatible). Sub-tables like + * `[mcp_servers..http_headers]` are ignored. Returns undefined + * if the file or section is missing. + */ +export async function readTomlServerEntry( + filePath: string, + serverName: string +): Promise | undefined> { + let raw: string; + try { + raw = await readFile(filePath, "utf-8"); + } catch { + return undefined; + } + + const sectionHeader = `[mcp_servers.${serverName}]`; + const startIdx = raw.indexOf(sectionHeader); + if (startIdx === -1) return undefined; + + // The top-level table's values live between its header and the next `[...]` + // header (whether that's a sub-table like `[mcp_servers.foo.http_headers]` + // or an unrelated section). Sub-table values belong to the sub-table, not + // here, so excluding them is correct. + const rest = raw.slice(startIdx + sectionHeader.length); + const nextHeader = /^\[/m.exec(rest); + const block = nextHeader ? rest.slice(0, nextHeader.index) : rest; + + const entry: Record = {}; + const lineRe = /^([A-Za-z_][\w-]*)\s*=\s*(.+?)\s*$/gm; + let lineMatch: RegExpExecArray | null; + while ((lineMatch = lineRe.exec(block)) !== null) { + const [, key, valueText] = lineMatch; + try { + entry[key] = JSON.parse(valueText); + } catch { + // Skip values we can't parse as JSON (e.g., bare TOML numbers like 20) + } + } + return Object.keys(entry).length > 0 ? entry : undefined; +} + +/** + * True when `entry` looks like a stdio invocation of `@upstash/context7-mcp` + * (either `command: "npx", args: [..., "@upstash/context7-mcp", ...]` or + * OpenCode-style `command: ["npx", ..., "@upstash/context7-mcp", ...]`). + */ +export function isStdioContext7Entry(entry: unknown): entry is Record { + if (!entry || typeof entry !== "object") return false; + const e = entry as Record; + const refs = (s: unknown) => typeof s === "string" && s.includes(STDIO_PACKAGE); + + if (Array.isArray(e.command)) { + return (e.command as unknown[]).some(refs); + } + if (typeof e.command === "string" && Array.isArray(e.args)) { + return (e.args as unknown[]).some(refs); + } + return false; +} + +/** + * Extracts an existing per-server entry from an in-memory JSON config + * (e.g., the object returned by `readJsonConfig`). Returns `undefined` + * when the section, server, or entry shape is missing. + */ +export function getJsonServerEntry( + config: Record, + configKey: string, + serverName: string +): Record | undefined { + const section = config[configKey]; + if (!section || typeof section !== "object") return undefined; + const entry = (section as Record)[serverName]; + return entry && typeof entry === "object" ? (entry as Record) : undefined; +} + +function stripApiKeyPair(args: string[]): string[] { + const result: string[] = []; + for (let i = 0; i < args.length; i++) { + if (args[i] === "--api-key") { + i++; // skip the value too + continue; + } + result.push(args[i]); + } + return result; +} + +/** + * Returns a copy of `entry` with any existing `--api-key ` pair + * removed from args (or array-form command), then a new `--api-key ` + * appended when `apiKey` is provided. All other fields — including the + * package specifier (e.g., `@upstash/context7-mcp@latest`) — are preserved. + */ +export function patchStdioApiKey( + entry: Record, + apiKey: string | undefined +): Record { + if (Array.isArray(entry.command)) { + const cmd = stripApiKeyPair(entry.command as string[]); + if (apiKey) cmd.push("--api-key", apiKey); + return { ...entry, command: cmd }; + } + const args = Array.isArray(entry.args) ? stripApiKeyPair(entry.args as string[]) : []; + if (apiKey) args.push("--api-key", apiKey); + return { ...entry, args }; +} + +export function buildTomlServerBlock(serverName: string, entry: Record): string { + const lines: string[] = [`[mcp_servers.${serverName}]`]; + const headers = entry.headers as Record | undefined; + + for (const [key, value] of Object.entries(entry)) { + if (key === "headers") continue; + lines.push(`${key} = ${JSON.stringify(value)}`); + } + + if (headers && Object.keys(headers).length > 0) { + lines.push(""); + lines.push(`[mcp_servers.${serverName}.http_headers]`); + for (const [key, value] of Object.entries(headers)) { + lines.push(`${key} = ${JSON.stringify(value)}`); + } + } + + return lines.join("\n") + "\n"; +} + +export async function appendTomlServer( + filePath: string, + serverName: string, + entry: Record +): Promise<{ alreadyExists: boolean }> { + const block = buildTomlServerBlock(serverName, entry); + + let existing = ""; + try { + existing = await readFile(filePath, "utf-8"); + } catch {} + + const sectionHeader = `[mcp_servers.${serverName}]`; + const alreadyExists = existing.includes(sectionHeader); + + if (alreadyExists) { + const subPrefix = `[mcp_servers.${serverName}.`; + const startIdx = existing.indexOf(sectionHeader); + const rest = existing.slice(startIdx + sectionHeader.length); + + let endOffset = rest.length; + const re = /^\[/gm; + let m; + while ((m = re.exec(rest)) !== null) { + const lineEnd = rest.indexOf("\n", m.index); + const line = rest.slice(m.index, lineEnd === -1 ? undefined : lineEnd); + if (!line.startsWith(subPrefix)) { + endOffset = m.index; + break; + } + } + + const rawBefore = existing.slice(0, startIdx).replace(/\n+$/, ""); + const rawAfter = existing + .slice(startIdx + sectionHeader.length + endOffset) + .replace(/^\n+/, ""); + const before = rawBefore.length > 0 ? rawBefore + "\n\n" : ""; + const after = rawAfter.length > 0 ? "\n" + rawAfter : ""; + const content = before + block + after; + await mkdir(dirname(filePath), { recursive: true }); + await writeFile(filePath, content, "utf-8"); + } else { + const separator = + existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : ""; + await mkdir(dirname(filePath), { recursive: true }); + await writeFile(filePath, existing + separator + block, "utf-8"); + } + + return { alreadyExists }; +} + +export async function removeTomlServer( + filePath: string, + serverName: string +): Promise<{ removed: boolean }> { + let existing = ""; + try { + existing = await readFile(filePath, "utf-8"); + } catch { + return { removed: false }; + } + + const sectionHeader = `[mcp_servers.${serverName}]`; + const startIdx = existing.indexOf(sectionHeader); + if (startIdx === -1) { + return { removed: false }; + } + + const subPrefix = `[mcp_servers.${serverName}.`; + const rest = existing.slice(startIdx + sectionHeader.length); + + let endOffset = rest.length; + const re = /^\[/gm; + let match: RegExpExecArray | null; + while ((match = re.exec(rest)) !== null) { + const lineEnd = rest.indexOf("\n", match.index); + const line = rest.slice(match.index, lineEnd === -1 ? undefined : lineEnd); + if (!line.startsWith(subPrefix)) { + endOffset = match.index; + break; + } + } + + const rawBefore = existing.slice(0, startIdx).replace(/\n+$/, ""); + const rawAfter = existing.slice(startIdx + sectionHeader.length + endOffset).replace(/^\n+/, ""); + const content = [rawBefore, rawAfter].filter(Boolean).join("\n\n"); + + await mkdir(dirname(filePath), { recursive: true }); + await writeFile(filePath, content.length > 0 ? `${content}\n` : "", "utf-8"); + return { removed: true }; +} diff --git a/packages/cli/src/setup/templates.ts b/packages/cli/src/setup/templates.ts new file mode 100644 index 0000000..b8ddb04 --- /dev/null +++ b/packages/cli/src/setup/templates.ts @@ -0,0 +1,95 @@ +const GITHUB_RAW_URLS = [ + "https://raw.githubusercontent.com/upstash/context7/master/rules", + "https://raw.githubusercontent.com/upstash/context7/main/rules", +]; + +const FALLBACK_MCP = `Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs. + +Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts. + +## Steps + +1. \`resolve-library-id\` with the library name and the user's question. Use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs") +2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). Use version-specific IDs when the user mentions a version +3. \`query-docs\` with the selected library ID and the user's full question (not single words), scoped to a single concept. If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate \`query-docs\` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic +4. Answer using the fetched docs +`; + +const FALLBACK_CLI = `Use the \`ctx7\` CLI to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs. + +Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts. + +## Steps + +1. Resolve library: \`npx ctx7@latest library ""\` +2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try the full name with punctuation (e.g., "next.js" not "nextjs") +3. Fetch docs: \`npx ctx7@latest docs ""\` — run a separate \`docs\` command per distinct concept if the question spans multiple topics, unless it's about how they interact +4. Answer using the fetched documentation + +You MUST call \`library\` first to get a valid ID (format: \`/org/project\`) unless the user provides one directly. Use the user's full question as the query — specific and detailed queries return better results than vague single words, but keep each query to a single concept unless the question is about how concepts interact; combined multi-topic queries dilute ranking and return shallow results for each topic. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries. + +For version-specific docs, use \`/org/project/version\` from the \`library\` output (e.g., \`/vercel/next.js/v14.3.0\`). + +If a command fails with a quota error, inform the user and suggest \`npx ctx7@latest login\` or setting \`CONTEXT7_API_KEY\` env var for higher limits. Do not silently fall back to training data. +`; + +const CURSOR_FRONTMATTER = `---\nalwaysApply: true\n---\n\n`; +const CODEX_CLI_SANDBOX_GUIDANCE = `Run Context7 CLI requests outside Codex's default sandbox. If a Context7 CLI 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 the sandbox.`; + +export type RuleMode = "mcp" | "cli"; + +async function fetchRule(filename: string, fallback: string): Promise { + for (const base of GITHUB_RAW_URLS) { + try { + const res = await fetch(`${base}/${filename}`); + if (res.ok) return await res.text(); + } catch { + continue; + } + } + return fallback; +} + +export async function getRuleContent(mode: RuleMode, agent: string): Promise { + const [filename, fallback] = + mode === "mcp" ? ["context7-mcp.md", FALLBACK_MCP] : ["context7-cli.md", FALLBACK_CLI]; + let body = await fetchRule(filename, fallback); + + if (mode === "cli" && agent === "codex" && !body.includes(CODEX_CLI_SANDBOX_GUIDANCE)) { + body = `${body.trimEnd()}\n${CODEX_CLI_SANDBOX_GUIDANCE}\n`; + } + + return agent === "cursor" ? `${CURSOR_FRONTMATTER}${body}` : body; +} + +export function customizeSkillFilesForAgent( + agent: string, + skillName: string, + files: Array<{ path: string; content: string }> +): Array<{ path: string; content: string }> { + if (agent !== "codex" || skillName !== "find-docs") { + return files; + } + + return files.map((file) => { + if (file.path !== "SKILL.md" || file.content.includes(CODEX_CLI_SANDBOX_GUIDANCE)) { + return file; + } + + const marker = "## Step 1: Resolve a Library"; + const guidance = `${CODEX_CLI_SANDBOX_GUIDANCE}\n\n`; + + if (file.content.includes(marker)) { + return { + ...file, + content: file.content.replace(marker, `${guidance}${marker}`), + }; + } + + const separator = file.content.endsWith("\n") ? "\n" : "\n\n"; + return { + ...file, + content: `${file.content}${separator}${CODEX_CLI_SANDBOX_GUIDANCE}\n`, + }; + }); +} diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts new file mode 100644 index 0000000..0c74e09 --- /dev/null +++ b/packages/cli/src/types.ts @@ -0,0 +1,252 @@ +export interface SkillFile { + path: string; + content: string; +} + +// TODO(deprecate-skills-phase-2): Remove Skill Hub response types when +// deprecated `ctx7 skills ...` commands are deleted. Keep setup skill directory +// types below. +export interface Skill { + name: string; + description: string; + url: string; + installCount?: number; + trustScore?: number; +} + +export interface SkillSearchResult extends Skill { + project: string; +} + +export interface ListSkillsResponse { + project: string; + skills: Skill[]; + blockedSkillsCount?: number; + error?: string; + message?: string; +} + +export interface SingleSkillResponse extends Skill { + project: string; + error?: string; + message?: string; +} + +export interface SearchResponse { + results: SkillSearchResult[]; + error?: string; + message?: string; +} + +export interface DownloadResponse { + skill: Skill & { project: string }; + files: SkillFile[]; + error?: string; +} + +// Library search types +export interface LibrarySearchResult { + id: string; + title: string; + description: string; + branch: string; + totalSnippets: number; + totalTokens?: number; + stars?: number; + trustScore?: number; + benchmarkScore?: number; + versions?: string[]; +} + +export interface LibrarySearchResponse { + results: LibrarySearchResult[]; + searchFilterApplied?: boolean; + error?: string; + message?: string; +} + +// Skill generation types +export interface SkillQuestion { + question: string; + options: string[]; + recommendedIndex: number; +} + +export interface SkillQuestionsResponse { + questions: SkillQuestion[]; + error?: string; + message?: string; +} + +export interface SkillAnswer { + question: string; + answer: string; +} + +export interface LibraryInput { + id: string; + name: string; +} + +export interface StructuredGenerateInput { + motivation: string; + libraries: LibraryInput[]; + answers: SkillAnswer[]; + feedback?: string; + previousContent?: string; +} + +export interface ToolResultSnippet { + title: string; + content: string; +} + +export interface ProgressEvent { + type: "progress"; + message: string; +} + +export interface ToolResultEvent { + type: "tool_result"; + toolName: string; + query: string; + libraryId?: string; + results: ToolResultSnippet[]; +} + +export interface CompleteEvent { + type: "complete"; + content: string; + libraryName: string; +} + +export interface ErrorEvent { + type: "error"; + message: string; +} + +export type GenerateStreamEvent = ProgressEvent | ToolResultEvent | CompleteEvent | ErrorEvent; + +export type IDE = "claude" | "cursor" | "antigravity" | "universal"; + +export type Scope = "project" | "global"; + +export interface IDEOptions { + allAgents?: boolean; + claude?: boolean; + cursor?: boolean; + universal?: boolean; + antigravity?: boolean; +} + +export interface ScopeOptions { + global?: boolean; +} + +export type AddOptions = IDEOptions & ScopeOptions & { all?: boolean; yes?: boolean }; +export type SuggestOptions = IDEOptions & ScopeOptions; +export type ListOptions = IDEOptions & ScopeOptions & { json?: boolean }; +export type RemoveOptions = IDEOptions & ScopeOptions; +export type GenerateOptions = IDEOptions & + ScopeOptions & { + output?: string; + all?: boolean; + }; + +export interface InstallTargets { + ides: IDE[]; + scopes: Scope[]; +} + +export const IDE_PATHS: Record = { + claude: ".claude/skills", + cursor: ".cursor/skills", + antigravity: ".agent/skills", + universal: ".agents/skills", +}; + +export const IDE_GLOBAL_PATHS: Record = { + claude: ".claude/skills", + cursor: ".cursor/skills", + antigravity: ".agent/skills", + universal: ".agents/skills", +}; + +export const IDE_NAMES: Record = { + claude: "Claude Code", + cursor: "Cursor", + antigravity: "Antigravity", + universal: "Universal", +}; + +// Universal .agents/skills standard +// These agents read from .agents/skills/ natively — one install covers all of them. +export const UNIVERSAL_SKILLS_PATH = ".agents/skills"; +export const UNIVERSAL_SKILLS_GLOBAL_PATH = ".agents/skills"; + +// Display label for agents that read .agents/skills/ (includes agents beyond our IDE type) +export const UNIVERSAL_AGENTS_LABEL = "Amp, Codex, Gemini CLI, GitHub Copilot, OpenCode + more"; + +// Agents that still require their own vendor-specific skill directory. +export const VENDOR_SPECIFIC_AGENTS: IDE[] = ["claude", "cursor", "antigravity"]; + +export interface C7Config { + defaultIde: IDE; + defaultScope: "project" | "global"; +} + +export const DEFAULT_CONFIG: C7Config = { + defaultIde: "universal", + defaultScope: "project", +}; + +// Suggest endpoint types +export interface SuggestSkill extends SkillSearchResult { + matchedDep: string; +} + +export interface SuggestResponse { + skills: SuggestSkill[]; + error?: string; + message?: string; +} + +export interface SkillQuotaResponse { + used: number; + limit: number; + remaining: number; + tier: "free" | "pro" | "unlimited"; + resetDate: string | null; + message?: string; + error?: string; +} + +export interface CodeExample { + language: string; + code: string; +} + +export interface CodeSnippet { + codeTitle: string; + codeDescription: string; + codeLanguage: string; + codeTokens: number; + codeId: string; + pageTitle: string; + codeList: CodeExample[]; +} + +export interface InfoSnippet { + pageId?: string; + breadcrumb?: string; + content: string; + contentTokens: number; +} + +export interface ContextResponse { + codeSnippets: CodeSnippet[]; + infoSnippets: InfoSnippet[]; + error?: string; + message?: string; + redirectUrl?: string; +} diff --git a/packages/cli/src/utils/api.ts b/packages/cli/src/utils/api.ts new file mode 100644 index 0000000..50b039b --- /dev/null +++ b/packages/cli/src/utils/api.ts @@ -0,0 +1,361 @@ +import type { + ListSkillsResponse, + SingleSkillResponse, + SearchResponse, + SuggestResponse, + DownloadResponse, + LibrarySearchResponse, + SkillQuestionsResponse, + StructuredGenerateInput, + GenerateStreamEvent, + SkillQuotaResponse, + ContextResponse, +} from "../types.js"; +import { downloadSkillFromGitHub, getSkillFromGitHub } from "./github.js"; +import { VERSION } from "../constants.js"; + +let baseUrl = "https://context7.com"; + +export function getBaseUrl(): string { + return baseUrl; +} + +export function setBaseUrl(url: string): void { + baseUrl = url; +} + +// TODO(deprecate-skills-phase-2): Remove the Skill Hub API helpers in this file +// when deprecated `ctx7 skills ...` commands are deleted. +export async function listProjectSkills(project: string): Promise { + const params = new URLSearchParams({ project }); + const response = await fetch(`${baseUrl}/api/v2/skills?${params}`); + return (await response.json()) as ListSkillsResponse; +} + +export async function getSkill(project: string, skillName: string): Promise { + const params = new URLSearchParams({ project, skill: skillName }); + const response = await fetch(`${baseUrl}/api/v2/skills?${params}`); + return (await response.json()) as SingleSkillResponse; +} + +export async function searchSkills(query: string): Promise { + const params = new URLSearchParams({ query }); + const response = await fetch(`${baseUrl}/api/v2/skills?${params}`); + return (await response.json()) as SearchResponse; +} + +export async function suggestSkills( + dependencies: string[], + accessToken?: string +): Promise { + const headers: Record = { "Content-Type": "application/json" }; + if (accessToken) { + headers["Authorization"] = `Bearer ${accessToken}`; + } + const response = await fetch(`${baseUrl}/api/v2/skills/suggest`, { + method: "POST", + headers, + body: JSON.stringify({ dependencies }), + }); + return (await response.json()) as SuggestResponse; +} + +export async function downloadSkill(project: string, skillName: string): Promise { + const skillData = await getSkill(project, skillName); + + if (skillData.error) { + // handle private repo skills with env var + const ghResult = await getSkillFromGitHub(project, skillName); + if (ghResult.status !== "ok" || !ghResult.skill) { + return { + skill: { name: skillName, description: "", url: "", project }, + files: [], + error: skillData.message || skillData.error, + }; + } + + const { files, error } = await downloadSkillFromGitHub(ghResult.skill); + if (error) { + return { skill: ghResult.skill, files: [], error }; + } + return { skill: ghResult.skill, files }; + } + + const skill = { + name: skillData.name, + description: skillData.description, + url: skillData.url, + project: skillData.project, + }; + + const { files, error } = await downloadSkillFromGitHub(skill); + + if (error) { + return { skill, files: [], error }; + } + + return { skill, files }; +} + +export interface GenerateSkillResponse { + content: string; + libraryName: string; + error?: string; +} + +export async function searchLibraries( + query: string, + accessToken?: string +): Promise { + const params = new URLSearchParams({ query }); + const headers: Record = {}; + if (accessToken) { + headers["Authorization"] = `Bearer ${accessToken}`; + } + const response = await fetch(`${baseUrl}/api/v2/libs/search?${params}`, { headers }); + return (await response.json()) as LibrarySearchResponse; +} + +export async function getSkillQuota(accessToken: string): Promise { + const response = await fetch(`${baseUrl}/api/v2/skills/quota`, { + headers: { Authorization: `Bearer ${accessToken}` }, + }); + + if (!response.ok) { + const errorData = await response.json().catch(() => ({})); + return { + used: 0, + limit: 0, + remaining: 0, + tier: "free", + resetDate: null, + error: (errorData as { message?: string }).message || `HTTP error ${response.status}`, + }; + } + + return (await response.json()) as SkillQuotaResponse; +} + +export async function getSkillQuestions( + libraries: Array<{ id: string; name: string }>, + motivation: string, + accessToken?: string +): Promise { + const headers: Record = { "Content-Type": "application/json" }; + if (accessToken) { + headers["Authorization"] = `Bearer ${accessToken}`; + } + + const response = await fetch(`${baseUrl}/api/v2/skills/questions`, { + method: "POST", + headers, + body: JSON.stringify({ libraries, motivation }), + }); + + if (!response.ok) { + const errorData = await response.json().catch(() => ({})); + return { + questions: [], + error: (errorData as { message?: string }).message || `HTTP error ${response.status}`, + }; + } + + return (await response.json()) as SkillQuestionsResponse; +} + +export async function generateSkillStructured( + input: StructuredGenerateInput, + onEvent?: (event: GenerateStreamEvent) => void, + accessToken?: string +): Promise { + const headers: Record = { "Content-Type": "application/json" }; + if (accessToken) { + headers["Authorization"] = `Bearer ${accessToken}`; + } + + const response = await fetch(`${baseUrl}/api/v2/skills/generate`, { + method: "POST", + headers, + body: JSON.stringify(input), + }); + + const libraryName = input.libraries[0]?.name || "skill"; + return handleGenerateResponse(response, libraryName, onEvent); +} + +async function handleGenerateResponse( + response: Response, + libraryName: string, + onEvent?: (event: GenerateStreamEvent) => void +): Promise { + if (!response.ok) { + const errorData = await response.json().catch(() => ({})); + return { + content: "", + libraryName, + error: (errorData as { message?: string }).message || `HTTP error ${response.status}`, + }; + } + + const reader = response.body?.getReader(); + if (!reader) { + return { content: "", libraryName, error: "No response body" }; + } + + const decoder = new TextDecoder(); + let content = ""; + let finalLibraryName = libraryName; + let error: string | undefined; + let buffer = ""; // Buffer for incomplete lines across chunks + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + const chunk = decoder.decode(value, { stream: true }); + buffer += chunk; + + // Split by newline but keep track of incomplete lines + const lines = buffer.split("\n"); + // Keep the last element (may be incomplete) in the buffer + buffer = lines.pop() || ""; + + for (const line of lines) { + const trimmedLine = line.trim(); + if (!trimmedLine) continue; + + try { + const data = JSON.parse(trimmedLine) as GenerateStreamEvent; + + if (onEvent) { + onEvent(data); + } + + if (data.type === "complete") { + content = data.content || ""; + finalLibraryName = data.libraryName || libraryName; + } else if (data.type === "error") { + error = data.message; + } + } catch { + // Ignore malformed JSON lines + } + } + } + + // Process any remaining data in the buffer + if (buffer.trim()) { + try { + const data = JSON.parse(buffer.trim()) as GenerateStreamEvent; + if (onEvent) { + onEvent(data); + } + if (data.type === "complete") { + content = data.content || ""; + finalLibraryName = data.libraryName || libraryName; + } else if (data.type === "error") { + error = data.message; + } + } catch { + // Ignore malformed JSON + } + } + + return { content, libraryName: finalLibraryName, error }; +} + +function getAuthHeaders(accessToken?: string): Record { + const headers: Record = { + "X-Context7-Source": "cli", + "X-Context7-Client-IDE": "ctx7-cli", + "X-Context7-Client-Version": VERSION, + "X-Context7-Transport": "cli", + }; + const apiKey = process.env.CONTEXT7_API_KEY; + if (apiKey) { + headers["Authorization"] = `Bearer ${apiKey}`; + } else if (accessToken) { + headers["Authorization"] = `Bearer ${accessToken}`; + } + return headers; +} + +export async function resolveLibrary( + libraryName: string, + query?: string, + accessToken?: string +): Promise { + const params = new URLSearchParams({ libraryName }); + if (query) { + params.set("query", query); + } + + const response = await fetch(`${baseUrl}/api/v2/libs/search?${params}`, { + headers: getAuthHeaders(accessToken), + }); + + if (!response.ok) { + const errorData = (await response.json().catch(() => ({}))) as { + error?: string; + message?: string; + }; + return { + results: [], + error: errorData.error || `HTTP error ${response.status}`, + message: errorData.message, + }; + } + + return (await response.json()) as LibrarySearchResponse; +} + +export interface GetContextOptions { + type?: "json" | "txt"; +} + +export async function getLibraryContext( + libraryId: string, + query: string, + options?: GetContextOptions, + accessToken?: string +): Promise { + const params = new URLSearchParams({ libraryId, query }); + if (options?.type) { + params.set("type", options.type); + } + const headers = getAuthHeaders(accessToken); + const response = await fetch(`${baseUrl}/api/v2/context?${params}`, { + headers, + }); + + if (!response.ok) { + const errorData = (await response.json().catch(() => ({}))) as { + error?: string; + message?: string; + redirectUrl?: string; + }; + + if (response.status === 301 && errorData.redirectUrl) { + return { + codeSnippets: [], + infoSnippets: [], + error: errorData.error || "library_redirected", + message: errorData.message, + redirectUrl: errorData.redirectUrl, + }; + } + + return { + codeSnippets: [], + infoSnippets: [], + error: errorData.error || `HTTP error ${response.status}`, + message: errorData.message, + }; + } + + if (options?.type === "txt") { + return await response.text(); + } + + return (await response.json()) as ContextResponse; +} diff --git a/packages/cli/src/utils/auth.ts b/packages/cli/src/utils/auth.ts new file mode 100644 index 0000000..fecd1b2 --- /dev/null +++ b/packages/cli/src/utils/auth.ts @@ -0,0 +1,239 @@ +import * as fs from "fs"; +import * as os from "os"; +import { CLI_CLIENT_ID } from "../constants.js"; +import { getBaseUrl } from "./api.js"; +import { + CREDENTIALS_FILE_NAME, + getConfigDir, + getCredentialsFilePath, + getLegacyFilePath, + migrateLegacyFileSync, + resolveReadPathSync, +} from "./storage-paths.js"; + +export interface TokenData { + access_token: string; + refresh_token?: string; + token_type: string; + expires_in?: number; + expires_at?: number; + scope?: string; +} + +function ensureConfigDir(): void { + const configDir = getConfigDir(); + if (!fs.existsSync(configDir)) { + fs.mkdirSync(configDir, { recursive: true, mode: 0o700 }); + } +} + +// Credentials must never be group/world-readable, even if a migrated or +// pre-existing file carried looser permissions. +const CREDENTIALS_MODE = 0o600; + +export function saveTokens(tokens: TokenData): void { + const credentialsFile = getCredentialsFilePath(); + migrateLegacyFileSync(CREDENTIALS_FILE_NAME, credentialsFile, CREDENTIALS_MODE); + ensureConfigDir(); + const data = { + ...tokens, + expires_at: + tokens.expires_at ?? (tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : undefined), + }; + fs.writeFileSync(credentialsFile, JSON.stringify(data, null, 2), { mode: CREDENTIALS_MODE }); + // `mode` is ignored when the file already exists; enforce it explicitly. + fs.chmodSync(credentialsFile, CREDENTIALS_MODE); +} + +export function loadTokens(): TokenData | null { + const credentialsFile = resolveReadPathSync( + CREDENTIALS_FILE_NAME, + getCredentialsFilePath(), + CREDENTIALS_MODE + ); + if (!fs.existsSync(credentialsFile)) { + return null; + } + try { + const data = JSON.parse(fs.readFileSync(credentialsFile, "utf-8")); + return data as TokenData; + } catch { + return null; + } +} + +export function clearTokens(): boolean { + const credentialsFile = getCredentialsFilePath(); + let removed = false; + if (fs.existsSync(credentialsFile)) { + fs.unlinkSync(credentialsFile); + removed = true; + } + const legacyCredentialsFile = getLegacyFilePath(CREDENTIALS_FILE_NAME); + if (fs.existsSync(legacyCredentialsFile)) { + fs.unlinkSync(legacyCredentialsFile); + removed = true; + } + return removed; +} + +export function isTokenExpired(tokens: TokenData): boolean { + if (!tokens.expires_at) { + return false; + } + return Date.now() > tokens.expires_at - 60000; +} + +async function refreshAccessToken(refreshToken: string): Promise { + const response = await fetch(`${getBaseUrl()}/api/oauth/token`, { + method: "POST", + headers: { "Content-Type": "application/x-www-form-urlencoded" }, + body: new URLSearchParams({ + grant_type: "refresh_token", + client_id: CLI_CLIENT_ID, + refresh_token: refreshToken, + }).toString(), + }); + + if (!response.ok) { + const err = (await response.json().catch(() => ({}))) as TokenErrorResponse; + throw new Error(err.error_description || err.error || "Failed to refresh token"); + } + + return (await response.json()) as TokenData; +} + +/** + * Returns a valid access token, refreshing if expired. Returns null if no + * tokens are stored or refresh fails. Pre-0.5 installs may have OAuth tokens + * with a `refresh_token`; new installs hold long-lived API keys that never + * expire and skip the refresh path entirely. + */ +export async function getValidAccessToken(): Promise { + const tokens = loadTokens(); + if (!tokens) return null; + + if (!isTokenExpired(tokens)) { + return tokens.access_token; + } + + if (!tokens.refresh_token) { + return null; + } + + try { + const newTokens = await refreshAccessToken(tokens.refresh_token); + saveTokens(newTokens); + return newTokens.access_token; + } catch { + return null; + } +} + +interface TokenErrorResponse { + error?: string; + error_description?: string; +} + +export interface DeviceAuthorizationResponse { + device_code: string; + user_code: string; + verification_uri: string; + verification_uri_complete?: string; + expires_in: number; + /** Optional per RFC 8628 §3.2; clients MUST default to 5s when absent. */ + interval?: number; +} + +const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"; + +/** RFC 8628 §3.2 default poll interval when the server omits `interval`. */ +export const DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 5; + +export async function startDeviceAuthorization( + baseUrl: string, + clientId: string +): Promise { + // Hostname is shown on the server's verification page so the user can confirm + // that the device they're authorizing matches the one running the CLI + // (RFC 8628 §5.4 phishing resistance). Best-effort. + const params = new URLSearchParams({ client_id: clientId }); + try { + const hostname = os.hostname(); + if (hostname) params.set("hostname", hostname); + } catch { + // ignore + } + + const response = await fetch(`${baseUrl}/api/oauth/device/code`, { + method: "POST", + headers: { "Content-Type": "application/x-www-form-urlencoded" }, + body: params.toString(), + }); + + if (!response.ok) { + const err = (await response.json().catch(() => ({}))) as TokenErrorResponse; + throw new Error(err.error_description || err.error || "Failed to start device authorization"); + } + + return (await response.json()) as DeviceAuthorizationResponse; +} + +export interface PollDeviceTokenResult { + status: "approved" | "pending" | "slow_down" | "denied" | "expired" | "transient"; + tokens?: TokenData; + errorMessage?: string; +} + +export async function pollDeviceToken( + baseUrl: string, + clientId: string, + deviceCode: string +): Promise { + let response: Response; + try { + response = await fetch(`${baseUrl}/api/oauth/device/token`, { + method: "POST", + headers: { "Content-Type": "application/x-www-form-urlencoded" }, + body: new URLSearchParams({ + grant_type: DEVICE_CODE_GRANT, + device_code: deviceCode, + client_id: clientId, + }).toString(), + }); + } catch (error) { + // Network blip — keep polling. + return { + status: "transient", + errorMessage: error instanceof Error ? error.message : "network error", + }; + } + + if (response.ok) { + const tokens = (await response.json()) as TokenData; + return { status: "approved", tokens }; + } + + // Treat any 5xx as transient so a flaky backend doesn't end the user's session. + if (response.status >= 500) { + const err = (await response.json().catch(() => ({}))) as TokenErrorResponse; + return { + status: "transient", + errorMessage: err.error_description || err.error || `HTTP ${response.status}`, + }; + } + + const err = (await response.json().catch(() => ({}))) as TokenErrorResponse; + switch (err.error) { + case "authorization_pending": + return { status: "pending" }; + case "slow_down": + return { status: "slow_down" }; + case "access_denied": + return { status: "denied" }; + case "expired_token": + return { status: "expired" }; + default: + throw new Error(err.error_description || err.error || "Device token poll failed"); + } +} diff --git a/packages/cli/src/utils/deps.ts b/packages/cli/src/utils/deps.ts new file mode 100644 index 0000000..18d48e5 --- /dev/null +++ b/packages/cli/src/utils/deps.ts @@ -0,0 +1,102 @@ +import { readFile } from "fs/promises"; +import { join } from "path"; + +async function readFileOrNull(path: string): Promise { + try { + return await readFile(path, "utf-8"); + } catch { + return null; + } +} + +/** Basic client-side filter. The real SKIP_SET lives on the backend. */ +function isSkippedLocally(name: string): boolean { + return name.startsWith("@types/"); +} + +async function parsePackageJson(cwd: string): Promise { + const content = await readFileOrNull(join(cwd, "package.json")); + if (!content) return []; + + try { + const pkg = JSON.parse(content); + const names = new Set(); + + for (const key of Object.keys(pkg.dependencies || {})) { + if (!isSkippedLocally(key)) names.add(key); + } + for (const key of Object.keys(pkg.devDependencies || {})) { + if (!isSkippedLocally(key)) names.add(key); + } + + return [...names]; + } catch { + return []; + } +} + +async function parseRequirementsTxt(cwd: string): Promise { + const content = await readFileOrNull(join(cwd, "requirements.txt")); + if (!content) return []; + + const deps: string[] = []; + for (const line of content.split("\n")) { + const trimmed = line.trim(); + if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("-")) continue; + const name = trimmed.split(/[=<>!~;@\s\[]/)[0].trim(); + if (name && !isSkippedLocally(name)) { + deps.push(name); + } + } + return deps; +} + +async function parsePyprojectToml(cwd: string): Promise { + const content = await readFileOrNull(join(cwd, "pyproject.toml")); + if (!content) return []; + + const deps: string[] = []; + const seen = new Set(); + + const projectDepsMatch = content.match(/\[project\]\s[\s\S]*?dependencies\s*=\s*\[([\s\S]*?)\]/); + if (projectDepsMatch) { + const entries = projectDepsMatch[1].match(/"([^"]+)"/g) || []; + for (const entry of entries) { + const name = entry + .replace(/"/g, "") + .split(/[=<>!~;@\s\[]/)[0] + .trim(); + if (name && !isSkippedLocally(name) && !seen.has(name)) { + seen.add(name); + deps.push(name); + } + } + } + + const poetryMatch = content.match(/\[tool\.poetry\.dependencies\]([\s\S]*?)(?:\n\[|$)/); + if (poetryMatch) { + const lines = poetryMatch[1].split("\n"); + for (const line of lines) { + const match = line.match(/^(\S+)\s*=/); + if (match) { + const name = match[1].trim(); + if (name && !isSkippedLocally(name) && name !== "python" && !seen.has(name)) { + seen.add(name); + deps.push(name); + } + } + } + } + + return deps; +} + +export async function detectProjectDependencies(cwd: string): Promise { + const results = await Promise.all([ + parsePackageJson(cwd), + parseRequirementsTxt(cwd), + parsePyprojectToml(cwd), + ]); + + return [...new Set(results.flat())]; +} diff --git a/packages/cli/src/utils/github.ts b/packages/cli/src/utils/github.ts new file mode 100644 index 0000000..f5518e9 --- /dev/null +++ b/packages/cli/src/utils/github.ts @@ -0,0 +1,311 @@ +import { execSync } from "node:child_process"; +import type { SkillFile, Skill } from "../types.js"; +import { isSafeSkillName } from "./skill-name.js"; + +const GITHUB_API = "https://api.github.com"; +const GITHUB_RAW = "https://raw.githubusercontent.com"; + +interface GitHubTreeItem { + path: string; + mode: string; + type: "blob" | "tree"; + sha: string; + size?: number; + url: string; +} + +interface GitHubTreeResponse { + sha: string; + url: string; + tree: GitHubTreeItem[]; + truncated: boolean; +} + +function parseGitHubUrl(url: string): { + owner: string; + repo: string; + branch: string; + path: string; +} | null { + try { + const urlObj = new URL(url); + const parts = urlObj.pathname.split("/").filter(Boolean); + + // Handle raw.githubusercontent.com URLs + // Format: https://raw.githubusercontent.com/owner/repo/refs/heads/branch/path/SKILL.md + if (urlObj.hostname === "raw.githubusercontent.com") { + if (parts.length < 5) return null; + + const owner = parts[0]; + const repo = parts[1]; + + // Handle refs/heads/branch format + if (parts[2] === "refs" && parts[3] === "heads") { + const branch = parts[4]; + // Get directory path (exclude the filename like SKILL.md) + const pathParts = parts.slice(5); + // Remove the last part if it looks like a file (has extension) + if (pathParts.length > 0 && pathParts[pathParts.length - 1].includes(".")) { + pathParts.pop(); + } + const path = pathParts.join("/"); + return { owner, repo, branch, path }; + } + + // Handle direct branch format: owner/repo/branch/path + const branch = parts[2]; + const pathParts = parts.slice(3); + if (pathParts.length > 0 && pathParts[pathParts.length - 1].includes(".")) { + pathParts.pop(); + } + const path = pathParts.join("/"); + return { owner, repo, branch, path }; + } + + // Handle github.com tree URLs + // Format: https://github.com/owner/repo/tree/branch/path + if (urlObj.hostname === "github.com") { + if (parts.length < 4 || parts[2] !== "tree") return null; + + const owner = parts[0]; + const repo = parts[1]; + const branch = parts[3]; + const path = parts.slice(4).join("/"); + + return { owner, repo, branch, path }; + } + + return null; + } catch { + return null; + } +} + +function getGitHubToken(): string | undefined { + const envToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN; + if (envToken) return envToken; + try { + return execSync("gh auth token", { stdio: ["pipe", "pipe", "ignore"] }) + .toString() + .trim(); + } catch { + return undefined; + } +} + +function parseSkillFrontmatter(content: string): { name: string; description: string } | null { + const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/); + if (!frontmatterMatch) return null; + + const frontmatter = frontmatterMatch[1]; + + const nameMatch = frontmatter.match(/^name:\s*(.+)$/m); + if (!nameMatch) return null; + const name = nameMatch[1].trim().replace(/^["']|["']$/g, ""); + if (!isSafeSkillName(name)) return null; + + let description = ""; + const multiLineMatch = frontmatter.match(/^description:\s*([|>])-?\s*$/m); + + if (multiLineMatch) { + const descLineIndex = frontmatter.indexOf("description:"); + const lines = frontmatter.slice(descLineIndex).split("\n").slice(1); + const indentedLines: string[] = []; + for (const line of lines) { + if (line.trim() === "") { + indentedLines.push(""); + continue; + } + if (/^\s+/.test(line)) { + indentedLines.push(line); + } else { + break; + } + } + const firstNonEmpty = indentedLines.find((l) => l.trim().length > 0); + const indent = firstNonEmpty?.match(/^(\s+)/)?.[1].length ?? 0; + description = indentedLines + .map((line) => line.slice(indent)) + .join(" ") + .replace(/\s+/g, " ") + .trim(); + } else { + const singleMatch = frontmatter.match(/^description:\s*(.+)$/m); + if (singleMatch) { + const value = singleMatch[1].trim(); + if (!["|", ">", "|-", ">-"].includes(value)) { + description = value.replace(/^["']|["']$/g, ""); + } + } + } + + if (!description) return null; + return { name, description }; +} + +function getGitHubHeaders(): Record { + const ghToken = getGitHubToken(); + return { + Accept: "application/vnd.github.v3+json", + "User-Agent": "context7-cli", + ...(ghToken && { Authorization: `token ${ghToken}` }), + }; +} + +async function extractGitHubError(response: Response): Promise { + let detail = `HTTP ${response.status}`; + try { + const body = (await response.json()) as { message?: string }; + if (body.message) detail += `: ${body.message}`; + } catch {} + return detail; +} + +async function fetchRepoTree( + owner: string, + repo: string, + branch: string, + headers: Record +): Promise { + const treeUrl = `${GITHUB_API}/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`; + const response = await fetch(treeUrl, { headers }); + if (!response.ok) return { error: await extractGitHubError(response) }; + return (await response.json()) as GitHubTreeResponse; +} + +async function fetchDefaultBranch( + owner: string, + repo: string, + headers: Record +): Promise<{ branch: string } | { error: string; status: number }> { + const response = await fetch(`${GITHUB_API}/repos/${owner}/${repo}`, { headers }); + if (!response.ok) return { error: await extractGitHubError(response), status: response.status }; + const data = (await response.json()) as { default_branch: string }; + return { branch: data.default_branch }; +} + +type GitHubSkillsResult = + | { status: "ok"; skills: (Skill & { project: string })[] } + | { status: "repo_not_found" } + | { status: "error"; error: string }; + +// TODO(deprecate-skills-phase-2): Remove direct GitHub Skill Hub fallback when +// deprecated `ctx7 skills install/info` commands are deleted. +export async function listSkillsFromGitHub(project: string): Promise { + try { + const parts = project.split("/").filter(Boolean); + if (parts.length < 2) return { status: "error", error: "Invalid project format" }; + const [owner, repo] = parts; + + const headers = getGitHubHeaders(); + const branchResult = await fetchDefaultBranch(owner, repo, headers); + if ("error" in branchResult) { + if (branchResult.status === 404) return { status: "repo_not_found" }; + return { status: "error", error: branchResult.error }; + } + + const treeData = await fetchRepoTree(owner, repo, branchResult.branch, headers); + if ("error" in treeData) return { status: "error", error: treeData.error }; + + const skillMdFiles = treeData.tree.filter( + (item) => item.type === "blob" && item.path.toLowerCase().endsWith("skill.md") + ); + + const skills: (Skill & { project: string })[] = []; + for (const item of skillMdFiles) { + const rawUrl = `${GITHUB_RAW}/${owner}/${repo}/${branchResult.branch}/${item.path}`; + const response = await fetch(rawUrl, { headers }); + if (!response.ok) continue; + + const content = await response.text(); + const meta = parseSkillFrontmatter(content); + if (!meta) continue; + + const skillDir = item.path.split("/").slice(0, -1).join("/"); + skills.push({ + name: meta.name, + description: meta.description, + url: `https://github.com/${owner}/${repo}/tree/${branchResult.branch}/${skillDir}`, + project, + }); + } + + return { status: "ok", skills }; + } catch (err) { + const message = err instanceof Error ? err.message : String(err); + return { status: "error", error: message }; + } +} + +export async function getSkillFromGitHub( + project: string, + skillName: string +): Promise { + const result = await listSkillsFromGitHub(project); + if (result.status !== "ok") return result; + const skill = result.skills.find((s) => s.name.toLowerCase() === skillName.toLowerCase()); + return { ...result, skill }; +} + +export async function downloadSkillFromGitHub( + skill: Skill & { project: string } +): Promise<{ files: SkillFile[]; error?: string }> { + try { + const parsed = parseGitHubUrl(skill.url); + + if (!parsed) { + return { files: [], error: `Invalid GitHub URL: ${skill.url}` }; + } + + const { owner, repo, branch, path: skillPath } = parsed; + + const ghHeaders = getGitHubHeaders(); + + const treeData = await fetchRepoTree(owner, repo, branch, ghHeaders); + if ("error" in treeData) { + const hint = + !ghHeaders["Authorization"] && /403|429|rate/.test(treeData.error) + ? " — run `gh auth login` or set the GITHUB_TOKEN env var to increase rate limits" + : ""; + return { files: [], error: `GitHub API error: ${treeData.error}${hint}` }; + } + + const skillFiles = treeData.tree.filter( + (item) => item.type === "blob" && item.path.startsWith(skillPath + "/") + ); + + if (skillFiles.length === 0) { + return { files: [], error: `No files found in ${skillPath}` }; + } + + const files: SkillFile[] = []; + for (const item of skillFiles) { + const rawUrl = `${GITHUB_RAW}/${owner}/${repo}/${branch}/${item.path}`; + const fileResponse = await fetch(rawUrl, { headers: ghHeaders }); + + if (!fileResponse.ok) { + console.warn(`Failed to fetch ${item.path}: ${fileResponse.status}`); + continue; + } + + const content = await fileResponse.text(); + const relativePath = item.path.slice(skillPath.length + 1); + + // Reject paths that attempt directory traversal + if (relativePath.includes("..")) { + console.warn(`Skipping file with unsafe path: ${item.path}`); + continue; + } + + files.push({ + path: relativePath, + content, + }); + } + + return { files }; + } catch (err) { + const message = err instanceof Error ? err.message : String(err); + return { files: [], error: message }; + } +} diff --git a/packages/cli/src/utils/ide.ts b/packages/cli/src/utils/ide.ts new file mode 100644 index 0000000..ce0e518 --- /dev/null +++ b/packages/cli/src/utils/ide.ts @@ -0,0 +1,289 @@ +import pc from "picocolors"; +import { select, confirm } from "@inquirer/prompts"; +import { access } from "fs/promises"; +import { join, dirname } from "path"; +import { homedir } from "os"; + +import { log } from "./logger.js"; +import { checkboxWithHover } from "./prompts.js"; +import type { + IDE, + IDEOptions, + Scope, + AddOptions, + ListOptions, + RemoveOptions, + InstallTargets, +} from "../types.js"; +import { + IDE_PATHS, + IDE_GLOBAL_PATHS, + IDE_NAMES, + UNIVERSAL_SKILLS_PATH, + UNIVERSAL_SKILLS_GLOBAL_PATH, + UNIVERSAL_AGENTS_LABEL, + VENDOR_SPECIFIC_AGENTS, + DEFAULT_CONFIG, +} from "../types.js"; + +export function getSelectedIdes(options: IDEOptions): IDE[] { + if (options.allAgents) { + return ["universal", ...VENDOR_SPECIFIC_AGENTS]; + } + + const ides: IDE[] = []; + if (options.claude) ides.push("claude"); + if (options.cursor) ides.push("cursor"); + if (options.universal) ides.push("universal"); + if (options.antigravity) ides.push("antigravity"); + return ides; +} + +export function hasExplicitIdeOption(options: IDEOptions): boolean { + return !!( + options.allAgents || + options.claude || + options.cursor || + options.universal || + options.antigravity + ); +} + +/** Detect vendor-specific agents whose parent directory exists. */ +async function detectVendorSpecificAgents(scope: Scope): Promise { + const baseDir = scope === "global" ? homedir() : process.cwd(); + const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS; + const detected: IDE[] = []; + + for (const ide of VENDOR_SPECIFIC_AGENTS) { + const parentDir = dirname(pathMap[ide]); + try { + await access(join(baseDir, parentDir)); + detected.push(ide); + } catch {} + } + + return detected; +} + +export function getUniversalDir(scope: Scope): string { + if (scope === "global") { + return join(homedir(), UNIVERSAL_SKILLS_GLOBAL_PATH); + } + return join(process.cwd(), UNIVERSAL_SKILLS_PATH); +} + +export async function promptForInstallTargets( + options: AddOptions, + forceUniversal = true +): Promise { + if (hasExplicitIdeOption(options)) { + const ides = getSelectedIdes(options); + const scope: Scope = options.global ? "global" : "project"; + return { + ides: ides.length > 0 ? ides : [DEFAULT_CONFIG.defaultIde], + scopes: [scope], + }; + } + + const scope: Scope = options.global ? "global" : "project"; + const baseDir = scope === "global" ? homedir() : process.cwd(); + const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS; + const universalPath = scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH; + + // Detect universal (.agents/) and vendor-specific agent directories + const detectedVendor = await detectVendorSpecificAgents(scope); + let hasUniversalDir = false; + try { + await access(join(baseDir, dirname(universalPath))); + hasUniversalDir = true; + } catch {} + + const detectedIdes: IDE[] = [ + ...(hasUniversalDir ? (["universal"] as IDE[]) : []), + ...detectedVendor, + ]; + + if (detectedIdes.length > 0) { + // Detected — just confirm + const pathLines: string[] = []; + if (hasUniversalDir) { + pathLines.push(join(baseDir, universalPath)); + } + for (const ide of detectedVendor) { + pathLines.push(join(baseDir, pathMap[ide])); + } + + log.blank(); + + let confirmed: boolean; + if (options.yes) { + confirmed = true; + } else { + try { + confirmed = await confirm({ + message: `Install to detected location(s)?\n${pc.dim(pathLines.join("\n"))}`, + default: true, + }); + } catch { + return null; + } + } + + if (!confirmed) { + log.warn("Installation cancelled"); + return null; + } + + return { ides: detectedIdes, scopes: [scope] }; + } + + // Nothing detected — show checkbox to pick + const universalLabel = `Universal \u2014 ${UNIVERSAL_AGENTS_LABEL} ${pc.dim(`(${universalPath})`)}`; + const choices: { name: string; value: IDE; checked: boolean }[] = [ + { + name: `${IDE_NAMES["claude"]} ${pc.dim(`(${pathMap["claude"]})`)}`, + value: "claude" as IDE, + checked: false, + }, + { name: universalLabel, value: "universal", checked: false }, + ]; + + for (const ide of VENDOR_SPECIFIC_AGENTS.filter((ide) => ide !== "claude")) { + choices.push({ + name: `${IDE_NAMES[ide]} ${pc.dim(`(${pathMap[ide]})`)}`, + value: ide, + checked: false, + }); + } + + log.blank(); + + let selectedIdes: IDE[]; + try { + selectedIdes = await checkboxWithHover( + { + message: `Which agents do you want to install to?\n${pc.dim(` ${baseDir}`)}`, + choices, + loop: false, + theme: { + style: { + highlight: (text: string) => pc.green(text), + message: (text: string, status: string) => { + if (status === "done") return text.split("\n")[0]; + return pc.bold(text); + }, + }, + }, + }, + { getName: (ide: IDE) => IDE_NAMES[ide] } + ); + } catch { + return null; + } + + const ides: IDE[] = forceUniversal + ? ["universal", ...selectedIdes.filter((ide) => ide !== "universal")] + : selectedIdes; + + return { ides, scopes: [scope] }; +} + +export async function promptForSingleTarget( + options: ListOptions | RemoveOptions +): Promise<{ ide: IDE; scope: Scope } | null> { + if (hasExplicitIdeOption(options)) { + const ides = getSelectedIdes(options); + const ide = ides[0] || DEFAULT_CONFIG.defaultIde; + const scope: Scope = options.global ? "global" : "project"; + return { ide, scope }; + } + + log.blank(); + + const universalLabel = `Universal ${pc.dim(`(${UNIVERSAL_SKILLS_PATH})`)}`; + const choices: { name: string; value: IDE }[] = [ + { name: `${IDE_NAMES["claude"]} ${pc.dim(`(${IDE_PATHS["claude"]})`)}`, value: "claude" }, + { name: universalLabel, value: "universal" }, + ]; + + for (const ide of VENDOR_SPECIFIC_AGENTS.filter((ide) => ide !== "claude")) { + choices.push({ + name: `${IDE_NAMES[ide]} ${pc.dim(`(${IDE_PATHS[ide]})`)}`, + value: ide, + }); + } + + let selectedIde: IDE; + try { + selectedIde = await select({ + message: "Which location?", + choices, + default: DEFAULT_CONFIG.defaultIde, + loop: false, + theme: { style: { highlight: (text: string) => pc.green(text) } }, + }); + } catch { + return null; + } + + let selectedScope: Scope; + if (options.global !== undefined) { + selectedScope = options.global ? "global" : "project"; + } else { + try { + selectedScope = await select({ + message: "Which scope?", + choices: [ + { + name: `Project ${pc.dim("(current directory)")}`, + value: "project" as Scope, + }, + { + name: `Global ${pc.dim("(home directory)")}`, + value: "global" as Scope, + }, + ], + default: DEFAULT_CONFIG.defaultScope, + loop: false, + theme: { style: { highlight: (text: string) => pc.green(text) } }, + }); + } catch { + return null; + } + } + + return { ide: selectedIde, scope: selectedScope }; +} + +export function getTargetDirs(targets: InstallTargets): string[] { + const hasUniversal = targets.ides.some((ide) => ide === "universal"); + const dirs: string[] = []; + + for (const scope of targets.scopes) { + const baseDir = scope === "global" ? homedir() : process.cwd(); + + if (hasUniversal) { + const uniPath = scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH; + dirs.push(join(baseDir, uniPath)); + } + + for (const ide of targets.ides) { + if (ide === "universal") continue; + const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS; + dirs.push(join(baseDir, pathMap[ide])); + } + } + + return dirs; +} + +export function getTargetDirFromSelection(ide: IDE, scope: Scope): string { + if (ide === "universal") { + return getUniversalDir(scope); + } + if (scope === "global") { + return join(homedir(), IDE_GLOBAL_PATHS[ide]); + } + return join(process.cwd(), IDE_PATHS[ide]); +} diff --git a/packages/cli/src/utils/installer.ts b/packages/cli/src/utils/installer.ts new file mode 100644 index 0000000..83837b8 --- /dev/null +++ b/packages/cli/src/utils/installer.ts @@ -0,0 +1,49 @@ +import { mkdir, writeFile, rm, symlink, lstat } from "fs/promises"; +import { resolve, dirname } from "path"; + +import type { SkillFile } from "../types.js"; +import { assertSkillNameInRoot } from "./skill-name.js"; + +export async function installSkillFiles( + skillName: string, + files: SkillFile[], + skillsRoot: string +): Promise { + const skillDir = assertSkillNameInRoot(skillsRoot, skillName); + + for (const file of files) { + const filePath = resolve(skillDir, file.path); + + // Prevent directory traversal — resolved path must stay within skillDir + if ( + !filePath.startsWith(skillDir + "/") && + !filePath.startsWith(skillDir + "\\") && + filePath !== skillDir + ) { + throw new Error(`Skill file path "${file.path}" resolves outside the target directory`); + } + + const fileDir = dirname(filePath); + + await mkdir(fileDir, { recursive: true }); + await writeFile(filePath, file.content); + } +} + +export async function symlinkSkill( + skillName: string, + sourcePath: string, + skillsRoot: string +): Promise { + const targetPath = assertSkillNameInRoot(skillsRoot, skillName); + + try { + const stats = await lstat(targetPath); + if (stats.isSymbolicLink() || stats.isDirectory()) { + await rm(targetPath, { recursive: true }); + } + } catch {} + + await mkdir(skillsRoot, { recursive: true }); + await symlink(sourcePath, targetPath); +} diff --git a/packages/cli/src/utils/library-id.ts b/packages/cli/src/utils/library-id.ts new file mode 100644 index 0000000..f189d74 --- /dev/null +++ b/packages/cli/src/utils/library-id.ts @@ -0,0 +1,22 @@ +/** + * Recover a library ID that Git Bash mangled on Windows. + * + * Git Bash rewrites a leading-slash argument like "/facebook/react" into a + * Windows path under the Git install dir, e.g. "C:/Program Files/Git/facebook/react". + * We undo that so the "/owner/repo" format still works. + */ +export function recoverLibraryId(input: string): string { + // "//owner/repo" is the Git Bash escape that skips conversion; collapse it. + if (input.startsWith("//")) return input.replace(/^\/+/, "/"); + + // Normal library ID, nothing to recover. + if (input.startsWith("/")) return input; + + // Only a drive-letter path (e.g. "C:/...") can be a mangled ID. + if (!/^[A-Za-z]:[\\/]/.test(input)) return input; + + // Strip the Git install dir, keeping the "/owner/repo[/version]" tail. + const normalized = input.replace(/\\/g, "/"); + const match = normalized.match(/^[A-Za-z]:\/.*?\/(?:Git|PortableGit|git-bash)\/(.+)$/i); + return match ? `/${match[1]}` : input; +} diff --git a/packages/cli/src/utils/logger.ts b/packages/cli/src/utils/logger.ts new file mode 100644 index 0000000..6b67eca --- /dev/null +++ b/packages/cli/src/utils/logger.ts @@ -0,0 +1,37 @@ +import pc from "picocolors"; + +const ANSI_PATTERN = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g; + +function visibleLength(text: string): number { + return text.replace(ANSI_PATTERN, "").length; +} + +function padVisible(text: string, width: number): string { + const padding = Math.max(0, width - visibleLength(text)); + return text + " ".repeat(padding); +} + +export function box(lines: string[], color: (message: string) => string = pc.green): void { + const contentWidth = Math.max(...lines.map((line) => visibleLength(line)), 0); + const top = color(`┌${"─".repeat(contentWidth + 2)}┐`); + const bottom = color(`└${"─".repeat(contentWidth + 2)}┘`); + + console.log(top); + for (const line of lines) { + console.log(color("│ ") + padVisible(line, contentWidth) + color(" │")); + } + console.log(bottom); +} + +export const log = { + info: (message: string) => console.log(pc.cyan(message)), + success: (message: string) => console.log(pc.green(`✔ ${message}`)), + warn: (message: string) => console.log(pc.yellow(`⚠ ${message}`)), + error: (message: string) => console.log(pc.red(`✖ ${message}`)), + dim: (message: string) => console.log(pc.dim(message)), + item: (message: string) => console.log(pc.green(` ${message}`)), + itemAdd: (message: string) => console.log(` ${pc.green("+")} ${message}`), + plain: (message: string) => console.log(message), + blank: () => console.log(""), + box, +}; diff --git a/packages/cli/src/utils/parse-input.ts b/packages/cli/src/utils/parse-input.ts new file mode 100644 index 0000000..942b691 --- /dev/null +++ b/packages/cli/src/utils/parse-input.ts @@ -0,0 +1,25 @@ +export interface ParsedSkillInput { + type: "repo" | "url"; + owner: string; + repo: string; + branch?: string; + path?: string; +} + +export function parseSkillInput(input: string): ParsedSkillInput | null { + const urlMatch = input.match( + /(?:https?:\/\/)?github\.com\/([^\/]+)\/([^\/]+)\/tree\/([^\/]+)\/(.+)/ + ); + if (urlMatch) { + const [, owner, repo, branch, path] = urlMatch; + return { type: "url", owner, repo, branch, path }; + } + + const shortMatch = input.match(/^\/?([^\/]+)\/([^\/]+)$/); + if (shortMatch) { + const [, owner, repo] = shortMatch; + return { type: "repo", owner, repo }; + } + + return null; +} diff --git a/packages/cli/src/utils/prompts.ts b/packages/cli/src/utils/prompts.ts new file mode 100644 index 0000000..c6a09ed --- /dev/null +++ b/packages/cli/src/utils/prompts.ts @@ -0,0 +1,134 @@ +import pc from "picocolors"; +import { checkbox, type Separator } from "@inquirer/prompts"; +import readline from "readline"; + +type CheckboxConfig = Parameters>[0]; +type CheckboxChoice = Exclude["choices"][number], Separator | string>; + +/** + * Creates a clickable terminal hyperlink using OSC 8 escape sequence. + */ +export function terminalLink(text: string, url: string, color?: (s: string) => string): string { + const colorFn = color ?? ((s: string) => s); + return `\x1b]8;;${url}\x07${colorFn(text)}\x1b]8;;\x07 ${pc.white("↗")}`; +} + +/** + * Formats install count into a popularity star rating (4 stars). + * 0/unknown → ☆☆☆☆, <100 → ★☆☆☆, <500 → ★★☆☆, <1000 → ★★★☆, 1000+ → ★★★★ + */ +export function formatPopularity(count: number | undefined): string { + const filled = "★"; + const empty = "☆"; + const max = 4; + let stars: number; + if (count === undefined || count === 0) stars = 0; + else if (count < 100) stars = 1; + else if (count < 500) stars = 2; + else if (count < 1000) stars = 3; + else stars = 4; + + const filledPart = filled.repeat(stars); + const emptyPart = empty.repeat(max - stars); + if (stars === 0) return pc.dim(emptyPart); + return pc.yellow(filledPart) + pc.dim(emptyPart); +} + +/** + * Returns the install count as a human-readable range string. + */ +export function formatInstallRange(count: number | undefined): string { + if (count === undefined || count === 0) return "Unknown"; + if (count < 100) return "<100"; + if (count < 500) return "<500"; + if (count < 1000) return "<1,000"; + return "1,000+"; +} + +/** + * Formats trust score as High / Medium / Low label. + * Uses MCP reputation thresholds: >=7 High, >=4 Medium, <4 Low. + */ +export function formatTrust(score: number | undefined): string { + if (score === undefined || score < 0) return pc.dim("-"); + if (score >= 7) return pc.green("High"); + if (score >= 4) return pc.yellow("Medium"); + return pc.red("Low"); +} + +/** + * Returns the raw trust label string (uncolored) for width calculations. + */ +export function getTrustLabel(score: number | undefined): string { + if (score === undefined || score < 0) return "-"; + if (score >= 7) return "High"; + if (score >= 4) return "Medium"; + return "Low"; +} +export interface CheckboxWithHoverOptions { + /** Function to extract display name from value. Defaults to (v) => v.name */ + getName?: (value: T) => string; +} + +export async function checkboxWithHover( + config: CheckboxConfig, + options?: CheckboxWithHoverOptions +): Promise { + const choices = config.choices.filter( + (c): c is CheckboxChoice => + typeof c === "object" && c !== null && !("type" in c && c.type === "separator") + ); + const values = choices.map((c) => c.value); + const totalItems = values.length; + let cursorPosition = choices.findIndex((c) => !c.disabled); + if (cursorPosition < 0) cursorPosition = 0; + + // Default getName assumes object has 'name' property + const getName = options?.getName ?? ((v: T) => (v as { name: string }).name); + + const keypressHandler = (_str: string | undefined, key: readline.Key) => { + if (key.name === "up") { + let next = cursorPosition - 1; + while (next >= 0 && choices[next].disabled) next--; + if (next >= 0) cursorPosition = next; + } else if (key.name === "down") { + let next = cursorPosition + 1; + while (next < totalItems && choices[next].disabled) next++; + if (next < totalItems) cursorPosition = next; + } + }; + + readline.emitKeypressEvents(process.stdin); + process.stdin.on("keypress", keypressHandler); + + const customConfig = { + ...config, + theme: { + ...config.theme, + style: { + answer: (text: string) => pc.green(text), + ...config.theme?.style, + highlight: (text: string) => pc.green(text), + renderSelectedChoices: ( + selected: CheckboxChoice[], + _allChoices: CheckboxChoice[] + ): string => { + if (selected.length === 0) { + return pc.dim(getName(values[cursorPosition])); + } + return selected.map((c) => getName(c.value)).join(", "); + }, + }, + }, + }; + + try { + const selected = await checkbox(customConfig); + if (selected.length === 0) { + return [values[cursorPosition]]; + } + return selected; + } finally { + process.stdin.removeListener("keypress", keypressHandler); + } +} diff --git a/packages/cli/src/utils/selectOrInput.ts b/packages/cli/src/utils/selectOrInput.ts new file mode 100644 index 0000000..78fb630 --- /dev/null +++ b/packages/cli/src/utils/selectOrInput.ts @@ -0,0 +1,111 @@ +import { + createPrompt, + useState, + useKeypress, + usePrefix, + isEnterKey, + isUpKey, + isDownKey, +} from "@inquirer/core"; +import type { KeypressEvent } from "@inquirer/core"; +import pc from "picocolors"; + +export interface SelectOrInputConfig { + message: string; + options: string[]; + recommendedIndex?: number; +} + +function reorderOptions(options: string[], recommendedIndex: number): string[] { + if (recommendedIndex === 0) return options; + const reordered = [options[recommendedIndex]]; + for (let i = 0; i < options.length; i++) { + if (i !== recommendedIndex) reordered.push(options[i]); + } + return reordered; +} + +const selectOrInput: (config: SelectOrInputConfig) => Promise = createPrompt< + string, + SelectOrInputConfig +>((config, done): string => { + const { message, options: rawOptions, recommendedIndex = 0 } = config; + const options = reorderOptions(rawOptions, recommendedIndex); + const [cursor, setCursor] = useState(0); + const [inputValue, setInputValue] = useState(""); + + const prefix = usePrefix({}); + + useKeypress((key: KeypressEvent, rl) => { + if (isUpKey(key)) { + setCursor(Math.max(0, cursor - 1)); + return; + } + + if (isDownKey(key)) { + setCursor(Math.min(options.length, cursor + 1)); + return; + } + + if (isEnterKey(key)) { + if (cursor === options.length) { + const finalValue = inputValue.trim(); + done(finalValue || options[0]); + } else { + done(options[cursor]); + } + return; + } + + // Text input handling (only when on custom input line) + if (cursor === options.length && key.name !== "return") { + if ((key.name === "w" && key.ctrl) || key.name === "backspace") { + if (key.name === "w" && key.ctrl) { + const words = inputValue.trimEnd().split(/\s+/); + if (words.length > 0) { + words.pop(); + setInputValue( + words.join(" ") + (inputValue.endsWith(" ") && words.length > 0 ? " " : "") + ); + } + } else { + setInputValue(inputValue.slice(0, -1)); + } + } else if (key.name === "u" && key.ctrl) { + setInputValue(""); + } else if (key.name === "space") { + setInputValue(inputValue + " "); + } else if (key.name && key.name.length === 1 && !key.ctrl) { + setInputValue(inputValue + key.name); + } + } else if (rl.line) { + rl.line = ""; + } + }); + + let output = `${prefix} ${pc.bold(message)}\n\n`; + + options.forEach((opt: string, idx: number) => { + const isRecommended = idx === 0; + const isCursor = idx === cursor; + const number = pc.cyan(`${idx + 1}.`); + const text = isRecommended ? `${opt} ${pc.green("✓ Recommended")}` : opt; + + if (isCursor) { + output += pc.cyan(`❯ ${number} ${text}\n`); + } else { + output += ` ${number} ${text}\n`; + } + }); + + const isCustomCursor = cursor === options.length; + if (isCustomCursor) { + output += pc.cyan(`❯ ${pc.yellow("✎")} ${inputValue || pc.dim("Type your own...")}`); + } else { + output += ` ${pc.yellow("✎")} ${pc.dim("Type your own...")}`; + } + + return output; +}); + +export default selectOrInput; diff --git a/packages/cli/src/utils/skill-name.ts b/packages/cli/src/utils/skill-name.ts new file mode 100644 index 0000000..d5150f0 --- /dev/null +++ b/packages/cli/src/utils/skill-name.ts @@ -0,0 +1,24 @@ +import { resolve, dirname, basename } from "path"; + +const SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/; + +export function isSafeSkillName(name: string): boolean { + if (typeof name !== "string") return false; + if (name.length === 0 || name.length > 128) return false; + if (name === "." || name === "..") return false; + if (name.includes("\0")) return false; + if (!SAFE_NAME.test(name)) return false; + return true; +} + +export function assertSkillNameInRoot(skillsRoot: string, skillName: string): string { + if (!isSafeSkillName(skillName)) { + throw new Error(`Unsafe skill name: ${JSON.stringify(skillName)}`); + } + const root = resolve(skillsRoot); + const target = resolve(root, skillName); + if (dirname(target) !== root || basename(target) !== skillName) { + throw new Error(`Skill name "${skillName}" escapes the skills root`); + } + return target; +} diff --git a/packages/cli/src/utils/storage-paths.ts b/packages/cli/src/utils/storage-paths.ts new file mode 100644 index 0000000..6ed6193 --- /dev/null +++ b/packages/cli/src/utils/storage-paths.ts @@ -0,0 +1,129 @@ +import * as fs from "fs"; +import { access, chmod, mkdir, rename } from "fs/promises"; +import * as os from "os"; +import * as path from "path"; + +const APP_DIR = "context7"; +const LEGACY_DIR = ".context7"; + +export const CREDENTIALS_FILE_NAME = "credentials.json"; +export const UPDATE_STATE_FILE_NAME = "cli-state.json"; +export const PREVIEWS_DIR_NAME = "previews"; + +// Per the XDG Base Directory Spec, a relative (or empty) value must be ignored +// and the default used instead. +function xdgBase(envVar: string, ...defaultSegments: string[]): string { + const value = process.env[envVar]; + const base = + value && path.isAbsolute(value) ? value : path.join(os.homedir(), ...defaultSegments); + return path.join(base, APP_DIR); +} + +export function getConfigDir(): string { + return xdgBase("XDG_CONFIG_HOME", ".config"); +} + +export function getStateDir(): string { + return xdgBase("XDG_STATE_HOME", ".local", "state"); +} + +export function getCacheDir(): string { + return xdgBase("XDG_CACHE_HOME", ".cache"); +} + +export function getCredentialsFilePath(): string { + return path.join(getConfigDir(), CREDENTIALS_FILE_NAME); +} + +export function getUpdateStateFilePath(): string { + return path.join(getStateDir(), UPDATE_STATE_FILE_NAME); +} + +export function getPreviewsDir(): string { + return path.join(getCacheDir(), PREVIEWS_DIR_NAME); +} + +export function getLegacyFilePath(fileName: string): string { + return path.join(os.homedir(), LEGACY_DIR, fileName); +} + +/** + * Best-effort move of a legacy `~/.context7/` into its new XDG location. + * `rename` preserves the source's permissions, so callers pass `mode` for + * sensitive files (e.g. credentials) to re-assert a restrictive mode on the + * migrated file. Failures (cross-device rename, permissions) are swallowed so + * callers fall back to reading the legacy file rather than crashing. + */ +export function migrateLegacyFileSync(fileName: string, targetPath: string, mode?: number): void { + const legacyPath = getLegacyFilePath(fileName); + if (legacyPath === targetPath || fs.existsSync(targetPath) || !fs.existsSync(legacyPath)) { + return; + } + + try { + fs.mkdirSync(path.dirname(targetPath), { recursive: true, mode: 0o700 }); + fs.renameSync(legacyPath, targetPath); + if (mode !== undefined) { + fs.chmodSync(targetPath, mode); + } + } catch { + // Leave the legacy file in place; readers resolve to it via resolveReadPathSync. + } +} + +export async function migrateLegacyFile( + fileName: string, + targetPath: string, + mode?: number +): Promise { + const legacyPath = getLegacyFilePath(fileName); + if (legacyPath === targetPath || (await exists(targetPath)) || !(await exists(legacyPath))) { + return; + } + + try { + await mkdir(path.dirname(targetPath), { recursive: true, mode: 0o700 }); + await rename(legacyPath, targetPath); + if (mode !== undefined) { + await chmod(targetPath, mode); + } + } catch { + // Leave the legacy file in place; readers resolve to it via resolveReadPath. + } +} + +/** + * Returns the path to read from: the XDG target after attempting migration, + * or the legacy path if migration could not complete and the legacy file + * still exists. New writes should always target `targetPath`. + */ +export function resolveReadPathSync(fileName: string, targetPath: string, mode?: number): string { + migrateLegacyFileSync(fileName, targetPath, mode); + if (fs.existsSync(targetPath)) { + return targetPath; + } + const legacyPath = getLegacyFilePath(fileName); + return fs.existsSync(legacyPath) ? legacyPath : targetPath; +} + +export async function resolveReadPath( + fileName: string, + targetPath: string, + mode?: number +): Promise { + await migrateLegacyFile(fileName, targetPath, mode); + if (await exists(targetPath)) { + return targetPath; + } + const legacyPath = getLegacyFilePath(fileName); + return (await exists(legacyPath)) ? legacyPath : targetPath; +} + +async function exists(filePath: string): Promise { + try { + await access(filePath); + return true; + } catch { + return false; + } +} diff --git a/packages/cli/src/utils/tracking.ts b/packages/cli/src/utils/tracking.ts new file mode 100644 index 0000000..c3ca149 --- /dev/null +++ b/packages/cli/src/utils/tracking.ts @@ -0,0 +1,10 @@ +import { getBaseUrl } from "./api.js"; + +export function trackEvent(event: string, data?: Record): void { + if (process.env.CTX7_TELEMETRY_DISABLED) return; + fetch(`${getBaseUrl()}/api/v2/cli/events`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ event, data }), + }).catch(() => {}); +} diff --git a/packages/cli/src/utils/update-check.ts b/packages/cli/src/utils/update-check.ts new file mode 100644 index 0000000..808d144 --- /dev/null +++ b/packages/cli/src/utils/update-check.ts @@ -0,0 +1,300 @@ +import { dirname } from "path"; +import { mkdir, readFile, writeFile } from "fs/promises"; +import { NAME, VERSION } from "../constants.js"; +import { + UPDATE_STATE_FILE_NAME, + getUpdateStateFilePath, + migrateLegacyFile, + resolveReadPath, +} from "./storage-paths.js"; + +const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000; + +export type InstallMethod = + | "npm-global" + | "pnpm-global" + | "bun-global" + | "npx" + | "pnpm-dlx" + | "bunx" + | "unknown"; + +interface UpdateState { + latestVersion?: string; + lastCheckedAt?: number; + notifiedVersion?: string; + lastNotifiedAt?: number; +} + +export interface UpgradePlan { + installMethod: InstallMethod; + command: string; + args: string[]; + displayCommand: string; + canRun: boolean; + needsExplicitVersion: boolean; +} + +export interface UpdateInfo { + currentVersion: string; + latestVersion: string; + updateAvailable: boolean; + installMethod: InstallMethod; + upgradePlan: UpgradePlan; +} + +interface CheckForUpdatesOptions { + force?: boolean; + now?: number; + cacheTtlMs?: number; + stateFile?: string; +} + +function getStateFilePath(stateFile?: string): string { + return stateFile ?? getUpdateStateFilePath(); +} + +// Reads resolve to the legacy `~/.context7` file if migration could not move it. +async function readStateFilePath(stateFile?: string): Promise { + if (stateFile) { + return stateFile; + } + return resolveReadPath(UPDATE_STATE_FILE_NAME, getUpdateStateFilePath()); +} + +// Writes always target the XDG path; migrate the legacy file first if present. +async function writeStateFilePath(stateFile?: string): Promise { + const path = getStateFilePath(stateFile); + if (!stateFile) { + await migrateLegacyFile(UPDATE_STATE_FILE_NAME, path); + } + return path; +} + +async function readUpdateState(stateFile?: string): Promise { + try { + const raw = await readFile(await readStateFilePath(stateFile), "utf-8"); + return JSON.parse(raw) as UpdateState; + } catch { + return {}; + } +} + +async function writeUpdateState(state: UpdateState, stateFile?: string): Promise { + const path = await writeStateFilePath(stateFile); + await mkdir(dirname(path), { recursive: true }); + await writeFile(path, JSON.stringify(state, null, 2) + "\n", "utf-8"); +} + +export function compareVersions(a: string, b: string): number { + const normalize = (version: string): number[] => + version + .split("-", 1)[0] + .split(".") + .map((part) => Number.parseInt(part, 10) || 0); + + const left = normalize(a); + const right = normalize(b); + const max = Math.max(left.length, right.length); + + for (let i = 0; i < max; i++) { + const diff = (left[i] ?? 0) - (right[i] ?? 0); + if (diff !== 0) return diff; + } + + return 0; +} + +export function detectInstallMethod(env: NodeJS.ProcessEnv = process.env): InstallMethod { + const execPath = env.npm_execpath?.toLowerCase() ?? ""; + const npmCommand = env.npm_command?.toLowerCase() ?? ""; + const userAgent = env.npm_config_user_agent?.toLowerCase() ?? ""; + + if (execPath.includes("pnpm") && npmCommand === "dlx") return "pnpm-dlx"; + if (execPath.includes("pnpm")) return "pnpm-global"; + if (execPath.includes("bun") && npmCommand === "x") return "bunx"; + if (execPath.includes("bun")) return "bun-global"; + if (execPath.includes("npm") && npmCommand === "exec") return "npx"; + if (execPath.includes("npm")) return "npm-global"; + + if (userAgent.startsWith("pnpm/")) return "pnpm-global"; + if (userAgent.startsWith("bun/")) return "bun-global"; + if (userAgent.startsWith("npm/")) return "npm-global"; + + return "unknown"; +} + +export function getUpgradePlan( + installMethod = detectInstallMethod(), + packageName = NAME +): UpgradePlan { + switch (installMethod) { + case "pnpm-global": + return { + installMethod, + command: "pnpm", + args: ["add", "-g", `${packageName}@latest`], + displayCommand: `pnpm add -g ${packageName}@latest`, + canRun: true, + needsExplicitVersion: false, + }; + case "bun-global": + return { + installMethod, + command: "bun", + args: ["add", "-g", `${packageName}@latest`], + displayCommand: `bun add -g ${packageName}@latest`, + canRun: true, + needsExplicitVersion: false, + }; + case "npx": + return { + installMethod, + command: "npx", + args: [`${packageName}@latest`], + displayCommand: `npx ${packageName}@latest `, + canRun: false, + needsExplicitVersion: true, + }; + case "pnpm-dlx": + return { + installMethod, + command: "pnpm", + args: ["dlx", `${packageName}@latest`], + displayCommand: `pnpm dlx ${packageName}@latest `, + canRun: false, + needsExplicitVersion: true, + }; + case "bunx": + return { + installMethod, + command: "bunx", + args: [`${packageName}@latest`], + displayCommand: `bunx ${packageName}@latest `, + canRun: false, + needsExplicitVersion: true, + }; + case "unknown": + return { + installMethod, + command: "npm", + args: ["install", "-g", `${packageName}@latest`], + displayCommand: `npm install -g ${packageName}@latest`, + canRun: false, + needsExplicitVersion: false, + }; + case "npm-global": + default: + return { + installMethod: "npm-global", + command: "npm", + args: ["install", "-g", `${packageName}@latest`], + displayCommand: `npm install -g ${packageName}@latest`, + canRun: true, + needsExplicitVersion: false, + }; + } +} + +async function fetchLatestVersion(packageName = NAME): Promise { + try { + const response = await fetch( + `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`, + { + headers: { Accept: "application/json" }, + signal: AbortSignal.timeout(1500), + } + ); + + if (!response.ok) return null; + + const data = (await response.json()) as { version?: unknown }; + return typeof data.version === "string" ? data.version : null; + } catch { + return null; + } +} + +export async function checkForUpdates( + options: CheckForUpdatesOptions = {} +): Promise { + const now = options.now ?? Date.now(); + const cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS; + const stateFile = options.stateFile; + const state = await readUpdateState(stateFile); + const isStale = + options.force || + !state.lastCheckedAt || + now - state.lastCheckedAt >= cacheTtlMs || + !state.latestVersion; + + let latestVersion = state.latestVersion ?? null; + + if (isStale) { + const fetchedVersion = await fetchLatestVersion(); + if (fetchedVersion) { + latestVersion = fetchedVersion; + await writeUpdateState( + { + ...state, + latestVersion: fetchedVersion, + lastCheckedAt: now, + }, + stateFile + ); + } + } + + if (!latestVersion) return null; + + const installMethod = detectInstallMethod(); + + return { + currentVersion: VERSION, + latestVersion, + updateAvailable: compareVersions(latestVersion, VERSION) > 0, + installMethod, + upgradePlan: getUpgradePlan(installMethod), + }; +} + +export async function shouldShowUpdateNotification( + info: UpdateInfo, + options: { now?: number; stateFile?: string; cooldownMs?: number } = {} +): Promise { + if (!info.updateAvailable) return false; + + const now = options.now ?? Date.now(); + const cooldownMs = options.cooldownMs ?? DEFAULT_CACHE_TTL_MS; + const state = await readUpdateState(options.stateFile); + + if ( + state.notifiedVersion === info.latestVersion && + state.lastNotifiedAt && + now - state.lastNotifiedAt < cooldownMs + ) { + return false; + } + + return true; +} + +export async function markUpdateNotificationShown( + latestVersion: string, + options: { now?: number; stateFile?: string } = {} +): Promise { + const now = options.now ?? Date.now(); + const state = await readUpdateState(options.stateFile); + await writeUpdateState( + { + ...state, + notifiedVersion: latestVersion, + lastNotifiedAt: now, + }, + options.stateFile + ); +} + +export function shouldSkipUpdateNotifier(argv = process.argv): boolean { + return argv.includes("--json") || argv.includes("-v") || argv.includes("--version"); +} diff --git a/packages/cli/tsconfig.json b/packages/cli/tsconfig.json new file mode 100644 index 0000000..3838119 --- /dev/null +++ b/packages/cli/tsconfig.json @@ -0,0 +1,21 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ESNext", + "moduleResolution": "bundler", + "lib": ["ES2022"], + "types": ["node"], + "outDir": "./dist", + "rootDir": "./src", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "resolveJsonModule": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts new file mode 100644 index 0000000..f06613a --- /dev/null +++ b/packages/cli/tsup.config.ts @@ -0,0 +1,20 @@ +import { defineConfig } from "tsup"; + +export default defineConfig({ + entry: ["src/index.ts"], + format: ["esm"], + dts: true, + clean: true, + sourcemap: true, + banner: { + js: "#!/usr/bin/env node", + }, + noExternal: [], + external: [ + "@inquirer/core", + "@inquirer/type", + "@inquirer/prompts", + "mute-stream", + "stream", + ], +}); diff --git a/packages/cli/vitest.config.ts b/packages/cli/vitest.config.ts new file mode 100644 index 0000000..0f78dc0 --- /dev/null +++ b/packages/cli/vitest.config.ts @@ -0,0 +1,9 @@ +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + globals: true, + environment: "node", + include: ["src/**/*.test.ts"], + }, +}); diff --git a/packages/mcp/.prettierignore b/packages/mcp/.prettierignore new file mode 100644 index 0000000..ad9d9b1 --- /dev/null +++ b/packages/mcp/.prettierignore @@ -0,0 +1,12 @@ +# Dependencies +node_modules + +# Build outputs +dist + +# Logs +*.log + +# Environment files +.env +.env.* diff --git a/packages/mcp/CHANGELOG.md b/packages/mcp/CHANGELOG.md new file mode 100644 index 0000000..cd3b15c --- /dev/null +++ b/packages/mcp/CHANGELOG.md @@ -0,0 +1,217 @@ +# @upstash/context7-mcp + +## 3.2.3 + +### Patch Changes + +- 41878ec: Skip loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16`), CGNAT (`100.64.0.0/10`), IPv6 loopback (`::1`), IPv6 link-local (`fe80::/10`), and IPv6 unique-local (`fc00::/7`) addresses when extracting the client IP from `X-Forwarded-For`, so proxy-internal hops no longer pollute the reported client IP. +- 33229cb: Clarify the `query-docs` query description so it asks for a single concept per query. When a question spans multiple distinct topics, callers are now told to make a separate query per concept instead of combining them (unless the question is about how the concepts interact), which avoids diluted, shallow results. Applied consistently across the MCP server, CLI, pi, and AI SDK tools. + +## 3.2.2 + +### Patch Changes + +- 2253765: Validate Enterprise-Managed Auth (id-jag) access tokens at the MCP server, so MCP clients can authenticate to Context7 through an enterprise IdP (Okta) via the MCP Enterprise-Managed Authorization extension. + +## 3.2.1 + +### Patch Changes + +- 8123b51: Restore Node 18 support by pinning undici to ^6.26.0 and commander to ^13.1.0, which dropped the Node 20+ engine requirements that caused a "File is not defined" crash on startup. + +## 3.2.0 + +### Minor Changes + +- c921c8b: Replace the in-result sign-in nudge with an MCP form elicitation. When the backend signals (via `X-Context7-Auth-Prompt: 1`) that an anonymous client has crossed the per-IP threshold, the MCP server now fires an `elicitation/create` request instead of appending instructions into the tool result. + - Surfaces the `npx ctx7 setup -- --mcp[ --stdio] -y` command in a client-rendered dialog rather than as model-visible text. The previous text-injection approach was treated as untrusted instruction content by some agents; elicitations are delivered out-of-band to the user so they bypass that path entirely. + - Gated on the client advertising the `elicitation` capability — clients without it see no nudge, which is a safe no-op. + - Presents a two-option radio: "I'll run the command to sign in" or "Continue anonymously with smaller limits". + - The server holds no suppression state: the backend emits the header at most once per MCP session, so the dialog is shown whenever the header is present. Frequency is owned entirely by the backend. + - Fire-and-forget: the elicitation does not block or alter the surrounding tool response. + +### Patch Changes + +- cb6aee1: Bump runtime dependencies: `@modelcontextprotocol/sdk` 1.25 -> 1.29, `undici` 6 -> 7, and `zod` 4.3 -> 4.4. +- fcdc36e: Advertise empty `prompts` and `resources` capabilities with no-op `prompts/list`, `resources/list`, and `resources/templates/list` handlers. Some MCP clients (e.g. opencode) call these unconditionally and treat `-32601 Method not found` as a fatal connection error rather than honoring the negotiated capabilities, which previously prevented the server from loading. + +## 3.1.0 + +### Minor Changes + +- 1fb2d42: Add multi-tenant Microsoft Entra ID validation for MCP tokens. The server now detects inbound Entra v2 tokens by issuer pattern, fetches per-teamspace configuration (`tenantId`, `audience`, `requiredScope`) from the Context7 app, and verifies the token against the matching tenant's JWKS, enforcing the required scope claim when configured. User resolution happens downstream in the Context7 app against a pre-provisioned user mapping table — the MCP server only validates. Per-tenant JWKS cache and a 5-minute in-memory config cache keyed by JWT audience reduce overhead under load. + +## 3.0.0 + +### Major Changes + +- af6a7b5: Convert the stateless MCP implementation to a stateful one using Redis for session management. + +### Patch Changes + +- 3d73145: Reduce Redis writes on `refresh` by checking the remaining TTL first and only issuing `EXPIRE` when the session is within one day of expiry. + +## 2.3.0 + +### Minor Changes + +- 34fda7d: Prompt anonymous users to sign in. After the backend signals (via the `X-Context7-Auth-Prompt: 1` response header on `/v2/libs/search` or `/v2/context`) that an anonymous client has crossed the per-IP threshold, the MCP server appends a one-time sign-in invitation to the tool result. + - Both **stdio** and **HTTP** transports surface the same nudge: a tool-result notice asking the assistant to run `npx ctx7 setup -- --mcp -y` (with `--stdio` appended when the MCP server is running on stdio) after explicit user confirmation. The CLI handles OAuth and writes credentials into the MCP client's config; the user restarts their MCP server / editor to pick up the new credentials. + - Detects the calling client from `X-Context7-Client-IDE` / User-Agent and selects the matching CLI flag (`--cursor`, `--claude`, `--codex`, `--opencode`, `--gemini`); falls back to interactive setup when unknown. + - HTTP transport remains stateless — the threshold is tracked by the backend (per-IP, 24h TTL), the MCP server only reacts to the signal. + +## 2.2.5 + +### Patch Changes + +- 187287c: Accept hallucinated argument names on `tools/call` requests by rewriting them to the canonical names before validation. `userQuery` and `question` are mapped to `query` on either tool; on `query-docs`, `context7CompatibleLibraryID`, `libraryID`, and `libraryName` are mapped to `libraryId`. Some LLM clients produce these alternative names — likely echoing phrasing from each tool's description — and previously triggered `Invalid input: expected string, received undefined` errors. `libraryName` is only rewritten on `query-docs` calls because it is the canonical arg for `resolve-library-id`. Tool input schemas published via `tools/list` are unchanged: canonical names remain the documented required fields, the rewrite is purely a server-side compatibility shim that runs only on `tools/call` and only when the canonical key is absent. +- 78b9826: Exit the stdio MCP server when the parent process closes its stdio. Previously, if the parent (e.g. Claude Code) was force-killed shortly after a tool call, an idle undici keep-alive socket to the Context7 API would keep libuv's event loop alive past stdin EOF, leaving an orphaned `node` process that consumed memory until the kernel tore the socket down (which on Cloudflare-fronted endpoints can take hours). The server now listens for `end`/`close` on stdin and `SIGHUP` and exits cleanly. Fixes #2542. + +## 2.2.4 + +### Patch Changes + +- d0e4a48: Create a fresh `McpServer` per HTTP request. Sharing one across requests let any concurrent `transport.close` clear the shared `Protocol._transport`, which broke `sendNotification` for in-flight long-running tool calls. +- 1aa3430: Remove research mode entirely from the MCP server and CLI. 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`. + +## 2.2.3 + +### Patch Changes + +- 772da3a: Stream MCP tool responses over SSE so HTTP headers flush before client `fetch` timeouts. Switching `enableJsonResponse` to `false` makes the SDK return the HTTP response synchronously after request validation, so headers are sent in milliseconds instead of being buffered until the tool completes. This fixes clients that cap the underlying `fetch` waiting for headers (e.g., Claude Code's 60s `wrapFetchWithTimeout`). + +## 2.2.2 + +### Patch Changes + +- 8274bd0: Add missing tool annotations +- ff6c1be: Remove the `researchMode` parameter from the `query-docs` tool's input schema. The underlying API still supports research mode, but several MCP clients hit per-request timeouts (60s defaults) on long-running research calls in ways that can't always be solved server-side. Hiding the parameter prevents agents from invoking it through MCP until the timeout story is reliable across clients. + +## 2.2.1 + +### Patch Changes + +- 1b0c211: Add endpoint for OpenAI Apps SDK domain verification. + +## 2.2.0 + +### Minor Changes + +- 17b864f: Expose research mode through the MCP `researchMode` tool and the CLI `docs --research` flag for deep, agent-driven documentation answers. + +## 2.1.8 + +### Patch Changes + +- 00833f9: Preserve Node's default trusted CAs when `NODE_EXTRA_CA_CERTS` is configured, and add a regression test for custom CA loading. + +## 2.1.7 + +### Patch Changes + +- 658ec67: Add --version/-v flag to MCP CLI +- 8322879: Improve resolve libryar id tool prompt to provide the libraryName query with proper format + +## 2.1.6 + +### Patch Changes + +- a667712: Update search filter warning +- be1a39a: Update server metadata and instructions. + +## 2.1.5 + +### Patch Changes + +- 2070cb1: Support NODE_EXTRA_CA_CERTS for enterprise MITM proxies by injecting custom CA certificates into undici's global dispatcher at runtime + +## 2.1.4 + +### Patch Changes + +- 9de3f06: Display warning when public library access filter is being used to filter libraries. + +## 2.1.3 + +### Patch Changes + +- 9523522: Reject GET requests on MCP endpoints with 405 to eliminate idle SSE connection timeouts +- 59d0327: Include source field in search result response + +## 2.1.2 + +### Patch Changes + +- 617d8ed: Remove unnecessary warning and update tool descriptions + +## 2.1.1 + +### Patch Changes + +- 02148ff: Bump zod from 3.x to 4.x + +## 2.1.0 + +### Minor Changes + +- ef82f30: Add OAuth 2.0 authentication support for MCP server + - Add new `/mcp/oauth` endpoint requiring JWT authentication + - Implement JWT validation against authorization server JWKS + - Add OAuth Protected Resource Metadata endpoint (RFC 9728) at `/.well-known/oauth-protected-resource` + - Include `WWW-Authenticate` header for OAuth discovery + +## 2.0.2 + +### Patch Changes + +- 368b143: Collect client and server version metrics + +## 2.0.1 + +### Patch Changes + +- 93a2d5b: Adds MCP tool annotations (readOnlyHint) to all tools to help MCP clients better understand tool behavior and make safer decisions about tool execution. + +## 2.0.0 + +### Major Changes + +- 66ea0d6: Upgrade MCP server to v2.0.0 with intelligent query-based architecture + + Breaking Changes + - Removed get-library-docs tool, replaced with new query-docs tool + - resolve-library-id now requires both query and libraryName parameters + - Removed mode, topic, page, and limit parameters from documentation fetching + - Renamed context7CompatibleLibraryID parameter to libraryId + + New Features + - Intelligent reranked and deduplicated library selection based on user intent + - Smart snippet selection with relevance-based ranking for documentation retrieval + - Query-driven context fetching that understands what the user is trying to accomplish + - Added security warnings for sensitive data in query parameters + - Added tool call limits (max 3 calls per question) to prevent excessive context window usage + + Improvements + - Simplified API key header extraction (removed redundant case variants) + - Removed unused actualPort variable and dead code + - Cleaner type definitions with new ContextRequest and ContextResponse types + - Better error messages for library search failures + +## 1.0.33 + +### Patch Changes + +- a5228fd: Fix API key not being passed in resolve-library-id tool when using stdio transport + +## 1.0.32 + +### Patch Changes + +- ad23996: Remove masked API key display from unauthorized error responses +- aa12390: Improve error message handling by using the responses from the server. + +## 1.0.31 + +### Patch Changes + +- 6255e26: Migrate to pnpm monorepo structure diff --git a/packages/mcp/Dockerfile b/packages/mcp/Dockerfile new file mode 100644 index 0000000..81720b4 --- /dev/null +++ b/packages/mcp/Dockerfile @@ -0,0 +1,29 @@ +# ----- Build Stage ----- +FROM node:lts-alpine AS builder +RUN corepack enable pnpm +WORKDIR /app + +# Copy monorepo config and install dependencies +COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.json ./ +COPY packages/mcp ./packages/mcp +RUN pnpm install --frozen-lockfile + +# Build the mcp package +RUN pnpm --filter @upstash/context7-mcp build + +# ----- Production Stage ----- +FROM node:lts-alpine +RUN corepack enable pnpm +WORKDIR /app + +# Install production dependencies only +COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./ +COPY packages/mcp/package.json ./packages/mcp/ +RUN pnpm install --frozen-lockfile --prod --filter @upstash/context7-mcp + +# Copy built files from builder +COPY --from=builder /app/packages/mcp/dist ./packages/mcp/dist + +WORKDIR /app/packages/mcp +EXPOSE 8080 +CMD ["node", "dist/index.js", "--transport", "http", "--port", "8080"] diff --git a/packages/mcp/LICENSE b/packages/mcp/LICENSE new file mode 100644 index 0000000..17900de --- /dev/null +++ b/packages/mcp/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2021 Upstash, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/mcp/README.md b/packages/mcp/README.md new file mode 100644 index 0000000..3c53ca5 --- /dev/null +++ b/packages/mcp/README.md @@ -0,0 +1,1611 @@ +![Cover](https://github.com/upstash/context7/blob/master/public/cover.png?raw=true) + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) [Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) + +# Context7 MCP - Up-to-date Code Docs For Any Prompt + +[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [![NPM Version](https://img.shields.io/npm/v/%40upstash%2Fcontext7-mcp?color=red)](https://www.npmjs.com/package/@upstash/context7-mcp) [![MIT licensed](https://img.shields.io/npm/l/%40upstash%2Fcontext7-mcp)](./LICENSE) + +[![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./i18n/README.zh-TW.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](./i18n/README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./i18n/README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./i18n/README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./i18n/README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./i18n/README.fr.md) [![Documentação em Português (Brasil)]()](./i18n/README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./i18n/README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./i18n/README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./i18n/README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./i18n/README.ru.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./i18n/README.uk.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./i18n/README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./i18n/README.ar.md) [![Tiếng Việt](https://img.shields.io/badge/docs-Tiếng%20Việt-red)](./i18n/README.vi.md) + +## ❌ Without Context7 + +LLMs rely on outdated or generic information about the libraries you use. You get: + +- ❌ Code examples are outdated and based on year-old training data +- ❌ Hallucinated APIs that don't even exist +- ❌ Generic answers for old package versions + +## ✅ With Context7 + +Context7 MCP pulls up-to-date, version-specific documentation and code examples straight from the source — and places them directly into your prompt. + +Add `use context7` to your prompt (or [set up a rule](#️-installation) to auto-invoke): + +```txt +Create a Next.js middleware that checks for a valid JWT in cookies +and redirects unauthenticated users to `/login`. use context7 +``` + +```txt +Configure a Cloudflare Worker script to cache +JSON API responses for five minutes. use context7 +``` + +Context7 fetches up-to-date code examples and documentation right into your LLM's context. + +- 1️⃣ Write your prompt naturally +- 2️⃣ Tell the LLM to `use context7` (or [set up a rule](#️-installation) once) +- 3️⃣ Get working code answers + +No tab-switching, no hallucinated APIs that don't exist, no outdated code generation. + +> [!NOTE] +> This repository hosts the source code of Context7 MCP server. The supporting components — API backend, parsing engine, and crawling engine — are private and not part of this release. + +## 📚 Adding Projects + +Check out our [project addition guide](https://context7.com/docs/adding-libraries) to learn how to add (or update) your favorite libraries to Context7. + +## 🛠️ Installation + +### Requirements + +- Node.js >= v18.0.0 +- Cursor, Claude Code, VSCode, Devin Desktop or another MCP Client +- Context7 API Key (Optional) for higher rate limits and private repositories (Get yours by creating an account at [context7.com/dashboard](https://context7.com/dashboard)) + +> [!TIP] +> **Recommended Post-Setup: Add a Rule to Auto-Invoke Context7** +> +> After installing Context7 (see instructions below), enhance your workflow by adding a rule so you don't have to type `use context7` in every prompt. Define a simple rule in your MCP client's rule section to automatically invoke Context7 on any code question: +> +> - For Devin Desktop, in `.devin/rules/` directory +> - For Cursor, from `Cursor Settings > Rules` section +> - For Claude Code, in `CLAUDE.md` file +> - Or the equivalent in your MCP client +> +> **Example Rule:** +> +> ```txt +> Always use context7 when I need code generation, setup or configuration steps, or +> library/API documentation. This means you should automatically use the Context7 MCP +> tools to resolve library id and get library docs without me having to explicitly ask. +> ``` +> +> From then on, you'll get Context7's docs in any related conversation without typing anything extra. You can alter the rule to match your use cases. + +
+Installing via Smithery + +To install Context7 MCP Server for any client automatically via [Smithery](https://smithery.ai/server/@upstash/context7-mcp): + +```bash +npx -y @smithery/cli@latest install @upstash/context7-mcp --client --key +``` + +You can find your Smithery key in the [Smithery.ai webpage](https://smithery.ai/server/@upstash/context7-mcp). + +
+ +
+Install in Cursor + +Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` + +Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info. + +> Since Cursor 1.0, you can click the install button below for instant one-click installation. + +#### Cursor Remote Server Connection + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Cursor Local Server Connection + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL2NvbnRleHQ3LW1jcCJ9) + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Install in Claude Code + +Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info. + +#### Claude Code Local Server Connection + +```sh +claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY +``` + +#### Claude Code Remote Server Connection + +```sh +claude mcp add --scope user --header "CONTEXT7_API_KEY: YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp +``` + +> Remove `--scope user` to install for the current project only. + +
+ +
+Install in Amp + +Run this command in your terminal. See [Amp MCP docs](https://ampcode.com/manual#mcp) for more info. + +#### Without API Key (Basic Usage) + +```sh +amp mcp add context7 https://mcp.context7.com/mcp +``` + +#### With API Key (Higher Rate Limits & Private Repos) + +```sh +amp mcp add context7 --header "CONTEXT7_API_KEY=YOUR_API_KEY" https://mcp.context7.com/mcp +``` + +
+ +
+Install in Devin Desktop + +Add this to your Devin Desktop MCP config file. See [Devin Desktop MCP docs](https://docs.devin.ai/desktop/cascade/mcp) for more info. + +#### Devin Desktop Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "serverUrl": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Devin Desktop Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Install in VS Code + +[Install in VS Code (npx)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) +[Install in VS Code Insiders (npx)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D) + +Add this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info. + +#### VS Code Remote Server Connection + +```json +"mcp": { + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### VS Code Local Server Connection + +```json +"mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+ +Install in Cline + + +You can easily install Context7 through the [Cline MCP Server Marketplace](https://cline.bot/mcp-marketplace) by following these instructions: + +1. Open **Cline**. +2. Click the hamburger menu icon (☰) to enter the **MCP Servers** section. +3. Use the search bar within the **Marketplace** tab to find _Context7_. +4. Click the **Install** button. + +Or you can directly edit MCP servers configuration: + +1. Open **Cline**. +2. Click the hamburger menu icon (☰) to enter the **MCP Servers** section. +3. Choose **Remote Servers** tab. +4. Click the **Edit Configuration** button. +5. Add context7 to `mcpServers`: + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp", + "type": "streamableHttp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` + +
+ +
+Install in Zed + +It can be installed via [Zed Extensions](https://zed.dev/extensions?query=Context7) or you can add this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info. + +```json +{ + "context_servers": { + "Context7": { + "source": "custom", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Install in Augment Code + +To configure Context7 MCP in Augment Code, you can use either the graphical interface or manual configuration. + +### **A. Using the Augment Code UI** + +1. Click the hamburger menu. +2. Select **Settings**. +3. Navigate to the **Tools** section. +4. Click the **+ Add MCP** button. +5. Enter the following command: + + ``` + npx -y @upstash/context7-mcp@latest + ``` + +6. Name the MCP: **Context7**. +7. Click the **Add** button. + +Once the MCP server is added, you can start using Context7's up-to-date code documentation features directly within Augment Code. + +--- + +### **B. Manual Configuration** + +1. Press Cmd/Ctrl Shift P or go to the hamburger menu in the Augment panel +2. Select Edit Settings +3. Under Advanced, click Edit in settings.json +4. Add the server configuration to the `mcpServers` array in the `augment.advanced` object + +```json +"augment.advanced": { + "mcpServers": [ + { + "name": "context7", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + ] +} +``` + +Once the MCP server is added, restart your editor. If you receive any errors, check the syntax to make sure closing brackets or commas are not missing. + +
+ +
+Install in Kilo Code + +You can configure the Context7 MCP server in **Kilo Code** using either the UI or by editing your project's MCP configuration file. + +Kilo Code supports two configuration levels: + +- **Global MCP Configuration** — stored in `mcp_settings.json` +- **Project-level MCP Configuration** — stored in `.kilocode/mcp.json` (recommended) + +If a server is defined in both places, the **project-level configuration overrides the global one**. + +--- + +## Configure via Kilo Code UI + +1. Open **Kilo Code**. +2. Click the **Settings** icon in the top-right corner. +3. Navigate to **Settings → MCP Servers**. +4. Click **Add Server**. +5. Choose **HTTP Server** (Streamable HTTP Transport). +6. Enter the details: + +**URL** +`https://mcp.context7.com/mcp` + +**Headers → Add Header** + +- **Key:** `Authorization` +- **Value:** `Bearer YOUR_API_KEY` + +7. Click **Save**. +8. Ensure the server toggle is **enabled**. +9. If needed, click **Refresh MCP Servers** to reload the configuration. + +--- + +## Manual Configuration (`.kilocode/mcp.json`) + +To configure the server at the project level (recommended for team environments), create the following file: + +**`.kilocode/mcp.json`:** + +```json +{ + "mcpServers": { + "context7": { + "type": "streamable-http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + }, + "alwaysAllow": [], + "disabled": false + } + } +} +``` + +Replace YOUR_API_KEY with your actual Context7 API key. + +After saving the file: + +- Open Settings → MCP Servers + +- Click Refresh MCP Servers + +Kilo Code will automatically detect and load the configuration. + +
+ +
+Install in Google Antigravity + +Add this to your Antigravity MCP config file. See [Antigravity MCP docs](https://antigravity.google/docs/mcp) for more info. + +#### Google Antigravity Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "serverUrl": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Google Antigravity Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Install in Roo Code + +Add this to your Roo Code MCP configuration file. See [Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo) for more info. + +#### Roo Code Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "type": "streamable-http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Roo Code Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Install in Gemini CLI + +See [Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) for details. + +1. Open the Gemini CLI settings file. The location is `~/.gemini/settings.json` (where `~` is your home directory). +2. Add the following to the `mcpServers` object in your `settings.json` file: + +```json +{ + "mcpServers": { + "context7": { + "httpUrl": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY", + "Accept": "application/json, text/event-stream" + } + } + } +} +``` + +Or, for a local server: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +If the `mcpServers` object does not exist, create it. + +
+ +
+Install in Qwen Coder + +See [Qwen Coder MCP Configuration](https://qwenlm.github.io/qwen-code-docs/en/tools/mcp-server/#how-to-set-up-your-mcp-server) for details. + +1. Open the Qwen Coder settings file. The location is `~/.qwen/settings.json` (where `~` is your home directory). +2. Add the following to the `mcpServers` object in your `settings.json` file: + +```json +{ + "mcpServers": { + "context7": { + "httpUrl": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY", + "Accept": "application/json, text/event-stream" + } + } + } +} +``` + +Or, for a local server: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +If the `mcpServers` object does not exist, create it. + +
+ +
+Install in Claude Desktop + +#### Remote Server Connection + +Open Claude Desktop and navigate to Settings > Connectors > Add Custom Connector. Enter the name as `Context7` and the remote MCP server URL as `https://mcp.context7.com/mcp`. + +#### Local Server Connection + +Open Claude Desktop developer settings and edit your `claude_desktop_config.json` file to add the following configuration. See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Install in Opencode + +Add this to your Opencode configuration file. See [Opencode MCP docs](https://opencode.ai/docs/mcp-servers) for more info. + +#### Opencode Remote Server Connection + +```json +"mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "enabled": true + } +} +``` + +#### Opencode Local Server Connection + +```json +{ + "mcp": { + "context7": { + "type": "local", + "command": ["npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "enabled": true + } + } +} +``` + +
+ +
+Install in OpenAI Codex + +See [OpenAI Codex](https://github.com/openai/codex) for more information. + +Add the following configuration to your OpenAI Codex MCP server settings: + +#### Local Server Connection + +```toml +[mcp_servers.context7] +args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] +command = "npx" +startup_timeout_ms = 20_000 +``` + +#### Remote Server Connection + +```toml +[mcp_servers.context7] +url = "https://mcp.context7.com/mcp" +http_headers = { "CONTEXT7_API_KEY" = "YOUR_API_KEY" } +``` + +> Optional troubleshooting — only if you see startup "request timed out" or "not found program". Most users can ignore this. +> +> - First try: increase `startup_timeout_ms` to `40_000` and retry. +> - Windows quick fix (absolute `npx` path + explicit env): +> +> ```toml +> [mcp_servers.context7] +> command = "C:\\Users\\yourname\\AppData\\Roaming\\npm\\npx.cmd" +> args = [ +> "-y", +> "@upstash/context7-mcp", +> "--api-key", +> "YOUR_API_KEY" +> ] +> env = { SystemRoot="C:\\Windows", APPDATA="C:\\Users\\yourname\\AppData\\Roaming" } +> startup_timeout_ms = 40_000 +> ``` +> +> - macOS quick fix (use Node + installed package entry point): +> +> ```toml +> [mcp_servers.context7] +> command = "/Users/yourname/.nvm/versions/node/v22.14.0/bin/node" +> args = ["/Users/yourname/.nvm/versions/node/v22.14.0/lib/node_modules/@upstash/context7-mcp/dist/index.js", +> "--transport", +> "stdio", +> "--api-key", +> "YOUR_API_KEY" +> ] +> ``` +> +> Notes: Replace `yourname` with your OS username. Explicitly setting `APPDATA` and `SystemRoot` is essential because these are required by `npx` on Windows but not set by certain versions of OpenAI Codex mcp clients by default. + +
+ +
+ +Install in JetBrains AI Assistant + +See [JetBrains AI Assistant Documentation](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) for more details. + +1. In JetBrains IDEs, go to `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)` +2. Click `+ Add`. +3. Click on `Command` in the top-left corner of the dialog and select the As JSON option from the list +4. Add this configuration and click `OK` + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +5. Click `Apply` to save changes. +6. The same way context7 could be added for JetBrains Junie in `Settings` -> `Tools` -> `Junie` -> `MCP Settings` + +
+ +
+ +Install in Kiro + +See [Kiro Model Context Protocol Documentation](https://kiro.dev/docs/mcp/configuration/) for details. + +[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=context7&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.context7.com%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D) + +1. Navigate `Kiro` > `MCP Servers` +2. Add a new MCP server by clicking the `+ Add` button. +3. Paste one of the configurations below: + +#### Kiro Remote Server Connection + +```json +{ + "mcpServers": { + "Context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +To use an API key in Kiro, add: + +```json +"headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" +} +``` + +You can create an API key at [context7.com/dashboard](https://context7.com/dashboard) for authenticated usage and higher rate limits. + +#### Kiro Local Server Connection + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "env": {}, + "disabled": false, + "autoApprove": [] + } + } +} +``` + +4. Click `Save` to apply the changes. + +
+ +
+Install in Trae + +Use the Add manually feature and fill in the JSON configuration information for that MCP server. +For more details, visit the [Trae documentation](https://docs.trae.ai/ide/model-context-protocol?_lang=en). + +#### Trae Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Trae Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Using Bun or Deno + +Use these alternatives to run the local Context7 MCP server with other runtimes. These examples work for any client that supports launching a local MCP server via command + args. + +#### Bun + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +#### Deno + +```json +{ + "mcpServers": { + "context7": { + "command": "deno", + "args": [ + "run", + "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", + "--allow-net", + "npm:@upstash/context7-mcp" + ] + } + } +} +``` + +
+ +
+Using Docker + +If you prefer to run the MCP server in a Docker container: + +1. **Build the Docker Image:** + + First, create a `Dockerfile` in the project root (or anywhere you prefer): + +
+ Click to see Dockerfile content + + ```Dockerfile + FROM node:18-alpine + + WORKDIR /app + + # Install the latest version globally + RUN npm install -g @upstash/context7-mcp + + # Expose default port if needed (optional, depends on MCP client interaction) + # EXPOSE 3000 + + # Default command to run the server + CMD ["context7-mcp", "--transport", "stdio"] + ``` + +
+ + Then, build the image using a tag (e.g., `context7-mcp`). **Make sure Docker Desktop (or the Docker daemon) is running.** Run the following command in the same directory where you saved the `Dockerfile`: + + ```bash + docker build -t context7-mcp . + ``` + +2. **Configure Your MCP Client:** + + Update your MCP client's configuration to use the Docker command. + + _Example for a cline_mcp_settings.json:_ + + ```json + { + "mcpServers": { + "Сontext7": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "docker", + "args": ["run", "-i", "--rm", "context7-mcp"], + "transportType": "stdio" + } + } + } + ``` + + _Note: This is an example configuration. Please refer to the specific examples for your MCP client (like Cursor, VS Code, etc.) earlier in this README to adapt the structure (e.g., `mcpServers` vs `servers`). Also, ensure the image name in `args` matches the tag used during the `docker build` command._ + + If you use the Docker MCP Toolkit image (`mcp/context7`) with a stdio-based client, + set `MCP_TRANSPORT=stdio` so the container starts with stdio transport instead of its + HTTP default. For Cline, Roo Code, and Claude Desktop, use: + + ```json + { + "mcpServers": { + "context7": { + "command": "docker", + "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "mcp/context7"] + } + } + } + ``` + + For VS Code, use the same Docker command in the `servers` format: + + ```json + { + "servers": { + "context7": { + "type": "stdio", + "command": "docker", + "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "mcp/context7"] + } + } + } + ``` + + Keep using the remote server URL for HTTP-based clients. + +
+ +
+Install Using the Desktop Extension + +Install the [context7.mcpb](mcpb/context7.mcpb) file under the mcpb folder and add it to your client. For more information, please check out [MCP bundles docs](https://github.com/anthropics/mcpb#mcp-bundles-mcpb). + +
+ +
+Install in Windows + +The configuration on Windows is slightly different compared to Linux or macOS (_`Cline` is used in the example_). The same principle applies to other editors; refer to the configuration of `command` and `args`. + +```json +{ + "mcpServers": { + "github.com/upstash/context7-mcp": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "disabled": false, + "autoApprove": [] + } + } +} +``` + +
+ +
+Install in Amazon Q Developer CLI + +Add this to your Amazon Q Developer CLI configuration file. See [Amazon Q Developer CLI docs](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html) for more details. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Install in Warp + +See [Warp Model Context Protocol Documentation](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) for details. + +1. Navigate `Settings` > `AI` > `Manage MCP servers`. +2. Add a new MCP server by clicking the `+ Add` button. +3. Paste the configuration given below: + +```json +{ + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "env": {}, + "working_directory": null, + "start_on_launch": true + } +} +``` + +4. Click `Save` to apply the changes. + +
+ +
+ +Install in Copilot Coding Agent + +## Using Context7 with Copilot Coding Agent + +Add the following configuration to the `mcp` section of your Copilot Coding Agent configuration file Repository->Settings->Copilot->Coding agent->MCP configuration: + +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["get-library-docs", "resolve-library-id"] + } + } +} +``` + +For more information, see the [official GitHub documentation](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). + +
+ +
+Install in Copilot CLI + +1. Open the Copilot CLI MCP config file. The location is `~/.copilot/mcp-config.json` (where `~` is your home directory). +2. Add the following to the `mcpServers` object in your `mcp-config.json` file: + +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + }, + "tools": ["get-library-docs", "resolve-library-id"] + } + } +} +``` + +Or, for a local server: + +```json +{ + "mcpServers": { + "context7": { + "type": "local", + "command": "npx", + "tools": ["get-library-docs", "resolve-library-id"], + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +If the `mcp-config.json` file does not exist, create it. + +
+ +
+Install in LM Studio + +See [LM Studio MCP Support](https://lmstudio.ai/blog/lmstudio-v0.3.17) for more information. + +#### One-click install: + +[![Add MCP Server context7 to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=context7&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB1cHN0YXNoL2NvbnRleHQ3LW1jcCJdfQ%3D%3D) + +#### Manual set-up: + +1. Navigate to `Program` (right side) > `Install` > `Edit mcp.json`. +2. Paste the configuration given below: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +3. Click `Save` to apply the changes. +4. Toggle the MCP server on/off from the right hand side, under `Program`, or by clicking the plug icon at the bottom of the chat box. + +
+ +
+Install in Visual Studio 2022 + +You can configure Context7 MCP in Visual Studio 2022 by following the [Visual Studio MCP Servers documentation](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022). + +Add this to your Visual Studio MCP config file (see the [Visual Studio docs](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) for details): + +```json +{ + "inputs": [], + "servers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +Or, for a local server: + +```json +{ + "mcp": { + "servers": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } + } +} +``` + +For more information and troubleshooting, refer to the [Visual Studio MCP Servers documentation](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022). + +
+ +
+Install in Crush + +Add this to your Crush configuration file. See [Crush MCP docs](https://github.com/charmbracelet/crush#mcps) for more info. + +#### Crush Remote Server Connection (HTTP) + +```json +{ + "$schema": "https://charm.land/crush.json", + "mcp": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +#### Crush Local Server Connection + +```json +{ + "$schema": "https://charm.land/crush.json", + "mcp": { + "context7": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Install in BoltAI + +Open the "Settings" page of the app, navigate to "Plugins," and enter the following JSON: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +Once saved, enter in the chat `get-library-docs` followed by your Context7 documentation ID (e.g., `get-library-docs /nuxt/ui`). More information is available on [BoltAI's Documentation site](https://docs.boltai.com/docs/plugins/mcp-servers). For BoltAI on iOS, [see this guide](https://docs.boltai.com/docs/boltai-mobile/mcp-servers). + +
+ +
+Install in Rovo Dev CLI + +Edit your Rovo Dev CLI MCP config by running the command below - + +```bash +acli rovodev mcp +``` + +Example config - + +#### Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +#### Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +
+Install in Zencoder + +To configure Context7 MCP in Zencoder, follow these steps: + +1. Go to the Zencoder menu (...) +2. From the dropdown menu, select Agent tools +3. Click on the Add custom MCP +4. Add the name and server configuration from below, and make sure to hit the Install button + +```json +{ + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] +} +``` + +Once the MCP server is added, you can easily continue using it. + +
+ +
+Install in Qodo Gen + +See [Qodo Gen docs](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps) for more details. + +1. Open Qodo Gen chat panel in VSCode or IntelliJ. +2. Click Connect more tools. +3. Click + Add new MCP. +4. Add the following configuration: + +#### Qodo Gen Local Server Connection + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +#### Qodo Gen Remote Server Connection + +```json +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +
+ +
+Install in Perplexity Desktop + +See [Local and Remote MCPs for Perplexity](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity) for more information. + +1. Navigate `Perplexity` > `Settings` +2. Select `Connectors`. +3. Click `Add Connector`. +4. Select `Advanced`. +5. Enter Server Name: `Context7` +6. Paste the following JSON in the text area: + +```json +{ + "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"], + "command": "npx", + "env": {} +} +``` + +7. Click `Save`. +
+ +
+Install in Factory + +Factory's droid supports MCP servers through its CLI. See [Factory MCP docs](https://docs.factory.ai/cli/configuration/mcp) for more info. + +#### Factory Remote Server Connection (HTTP) + +Run this command in your terminal: + +```sh +droid mcp add context7 https://mcp.context7.com/mcp --type http --header "CONTEXT7_API_KEY: YOUR_API_KEY" +``` + +Or without an API key (basic usage with rate limits): + +```sh +droid mcp add context7 https://mcp.context7.com/mcp --type http +``` + +#### Factory Local Server Connection (Stdio) + +Run this command in your terminal: + +```sh +droid mcp add context7 "npx -y @upstash/context7-mcp" --env CONTEXT7_API_KEY=YOUR_API_KEY +``` + +Once configured, Context7 tools will be available in your droid sessions. Type `/mcp` within droid to manage servers, authenticate, and view available tools. + +
+ +
+Install in Emdash + +[Emdash](https://github.com/generalaction/emdash) is an orchestration layer for running multiple coding agents in parallel. Provider-agnostic, worktree-isolated, and local-first. Emdash supports Context7 MCP to enable Context7 for your agents. + +**What Emdash provides:** + +- Global toggle: Settings → MCP → "Enable Context7 MCP" +- Per-workspace enable: The Context7 button in the ProviderBar (off by default). First click enables it for that workspace. Clicking again disables it. +- ProviderBar: The Context7 button shows status, a short explanation, and a link to docs + +**What you still need to do:** +Configure your coding agent (Codex, Claude Code, Cursor, etc.) to connect to Context7 MCP. Emdash does not modify your agent's config. See the respective MCP configuration sections above for your agent (e.g., OpenAI Codex, Claude Code, Cursor). + +See the [Emdash repository](https://github.com/generalaction/emdash) for more information. + +
+ +## 🔨 Available Tools + +Context7 MCP provides the following tools that LLMs can use: + +- `resolve-library-id`: Resolves a general library name into a Context7-compatible library ID. + - `libraryName` (required): The name of the library to search for + +- `get-library-docs`: Fetches documentation for a library using a Context7-compatible library ID. + - `context7CompatibleLibraryID` (required): Exact Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`) + - `topic` (optional): Focus the docs on a specific topic (e.g., "routing", "hooks") + - `page` (optional, default 1): Page number for pagination (1-10). If the context is not sufficient, try page=2, page=3, etc. with the same topic. + +## 🛟 Tips + +### Add a Rule + +To avoid typing `use context7` in every prompt, you can add a rule to your MCP client that automatically invokes Context7 for code-related questions. See the [recommended setup in the Installation section](#️-installation) for detailed instructions and example rules. + +### Use Library Id + +If you already know exactly which library you want to use, add its Context7 ID to your prompt. That way, Context7 MCP server can skip the library-matching step and directly continue with retrieving docs. + +```txt +Implement basic authentication with Supabase. use library /supabase/supabase for API and docs. +``` + +The slash syntax tells the MCP tool exactly which library to load docs for. + +### HTTPS Proxy + +If you are behind an HTTP proxy, Context7 uses the standard `https_proxy` / `HTTPS_PROXY` environment variables. + +## 💻 Development + +Clone the project and install dependencies: + +```bash +bun i +``` + +Build: + +```bash +bun run build +``` + +Run the server: + +```bash +bun run dist/index.js +``` + +### CLI Arguments + +`context7-mcp` accepts the following CLI flags: + +- `--transport ` – Transport to use (`stdio` by default). Use `http` for remote HTTP server or `stdio` for local integration. +- `--port ` – Port to listen on when using `http` transport (default `3000`). +- `--api-key ` – API key for authentication (or set `CONTEXT7_API_KEY` env var). You can get your API key by creating an account at [context7.com/dashboard](https://context7.com/dashboard). + +Example with HTTP transport and port 8080: + +```bash +bun run dist/index.js --transport http --port 8080 +``` + +Another example with stdio transport: + +```bash +bun run dist/index.js --transport stdio --api-key YOUR_API_KEY +``` + +### Environment Variables + +You can use the `CONTEXT7_API_KEY` environment variable instead of passing the `--api-key` flag. This is useful for: + +- Storing API keys securely in `.env` files +- Integration with MCP server setups that use dotenv +- Tools that prefer environment variable configuration + +**Note:** The `--api-key` CLI flag takes precedence over the environment variable when both are provided. + +**Example with .env file:** + +```bash +# .env +CONTEXT7_API_KEY=your_api_key_here +``` + +**Example MCP configuration using environment variable:** + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "CONTEXT7_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +
+Local Configuration Example + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["tsx", "/path/to/folder/context7/src/index.ts", "--api-key", "YOUR_API_KEY"] + } + } +} +``` + +
+ +### OAuth Authentication + +Context7 MCP server supports OAuth 2.0 authentication for MCP clients that implement the [MCP OAuth specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). + +To use OAuth, change the endpoint from `/mcp` to `/mcp/oauth` in your client configuration: + +```diff +- "url": "https://mcp.context7.com/mcp" ++ "url": "https://mcp.context7.com/mcp/oauth" +``` + +> **Note:** OAuth is not supported with stdio transport. For local MCP connections, use API key authentication instead. + +
+Testing with MCP Inspector + +```bash +npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp +``` + +
+ +## 🚨 Troubleshooting + +
+Module Not Found Errors + +If you encounter `ERR_MODULE_NOT_FOUND`, try using `bunx` instead of `npx`: + +```json +{ + "mcpServers": { + "context7": { + "command": "bunx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +This often resolves module resolution issues in environments where `npx` doesn't properly install or resolve packages. + +
+ +
+ESM Resolution Issues + +For errors like `Error: Cannot find module 'uriTemplate.js'`, try the `--experimental-vm-modules` flag: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"] + } + } +} +``` + +
+ +
+TLS/Certificate Issues + +Use the `--experimental-fetch` flag to bypass TLS-related problems: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"] + } + } +} +``` + +
+ +
+General MCP Client Errors + +1. Try adding `@latest` to the package name +2. Use `bunx` as an alternative to `npx` +3. Consider using `deno` as another alternative +4. Ensure you're using Node.js v18 or higher for native fetch support + +
+ +## ⚠️ Disclaimer + +1- Context7 projects are community-contributed and while we strive to maintain high quality, we cannot guarantee the accuracy, completeness, or security of all library documentation. Projects listed in Context7 are developed and maintained by their respective owners, not by Context7. If you encounter any suspicious, inappropriate, or potentially harmful content, please use the "Report" button on the project page to notify us immediately. We take all reports seriously and will review flagged content promptly to maintain the integrity and safety of our platform. By using Context7, you acknowledge that you do so at your own discretion and risk. + +2- This repository hosts the MCP server’s source code. The supporting components — API backend, parsing engine, and crawling engine — are private and not part of this release. + +## 🤝 Connect with Us + +Stay updated and join our community: + +- 📢 Follow us on [X](https://x.com/context7ai) for the latest news and updates +- 🌐 Visit our [Website](https://context7.com) +- 💬 Join our [Discord Community](https://upstash.com/discord) + +## 📺 Context7 In Media + +- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E) +- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs) +- [Income Stream Surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o) +- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc) +- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4) +- [Income Stream Surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M) +- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo) +- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM) + +## ⭐ Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date) + +## 📄 License + +MIT diff --git a/packages/mcp/eslint.config.js b/packages/mcp/eslint.config.js new file mode 100644 index 0000000..ae606cb --- /dev/null +++ b/packages/mcp/eslint.config.js @@ -0,0 +1,47 @@ +import { defineConfig } from "eslint/config"; +import tseslint from "typescript-eslint"; +import eslintPluginPrettier from "eslint-plugin-prettier"; + +export default defineConfig( + { + // Base ESLint configuration + ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"], + }, + { + files: ["**/*.ts", "**/*.tsx"], + languageOptions: { + ecmaVersion: 2020, + sourceType: "module", + parser: tseslint.parser, + parserOptions: { + project: ["./tsconfig.json", "./tsconfig.test.json"], + tsconfigRootDir: import.meta.dirname, + }, + globals: { + // Add Node.js globals + process: "readonly", + require: "readonly", + module: "writable", + console: "readonly", + }, + }, + // Settings for all files + linterOptions: { + reportUnusedDisableDirectives: true, + }, + plugins: { + "@typescript-eslint": tseslint.plugin, + prettier: eslintPluginPrettier, + }, + rules: { + // TypeScript recommended rules + ...tseslint.configs.recommended.rules, + // TypeScript rules + "@typescript-eslint/explicit-module-boundary-types": "off", + "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }], + "@typescript-eslint/no-explicit-any": "warn", + // Prettier integration + "prettier/prettier": "error", + }, + } +); diff --git a/packages/mcp/mcpb/.mcpbignore b/packages/mcp/mcpb/.mcpbignore new file mode 100644 index 0000000..febd03e --- /dev/null +++ b/packages/mcp/mcpb/.mcpbignore @@ -0,0 +1,25 @@ +# Source (dist/ is sufficient) +src/ +*.ts + +# Config files +eslint.config.js +prettier.config.mjs +smithery.yaml +tsconfig.json + +# Documentation +*.md +LICENSE + +# Docker +Dockerfile + +# Schema +schema/ + +# Assets (icon is copied to root) +public/* + +# MCPB meta (avoid nesting) +mcpb/ diff --git a/packages/mcp/mcpb/context7.mcpb b/packages/mcp/mcpb/context7.mcpb new file mode 100644 index 0000000..07fc604 Binary files /dev/null and b/packages/mcp/mcpb/context7.mcpb differ diff --git a/packages/mcp/mcpb/manifest.json b/packages/mcp/mcpb/manifest.json new file mode 100644 index 0000000..ec48790 --- /dev/null +++ b/packages/mcp/mcpb/manifest.json @@ -0,0 +1,49 @@ +{ + "manifest_version": "0.3", + "name": "context7", + "display_name": "Context7", + "version": "2.1.0", + "description": "Up-to-date Code Docs For Any Prompt", + "long_description": "Context7 MCP pulls up-to-date, version-specific documentation and code examples straight from the source — and places them directly into your prompt.", + "author": { + "name": "Upstash", + "email": "context7@upstash.com", + "url": "https://upstash.com" + }, + "homepage": "https://context7.com", + "documentation": "https://github.com/upstash/context7", + "support": "https://github.com/upstash/context7/issues", + "privacy_policies": ["https://upstash.com/privacy"], + "icon": "icon.png", + "server": { + "type": "node", + "entry_point": "dist/index.js", + "mcp_config": { + "command": "node", + "args": ["${__dirname}/dist/index.js"], + "env": {} + } + }, + "tools": [ + { + "name": "Resolve Context7 Library ID", + "description": "Resolves a package/product name to a Context7-compatible library ID and returns matching libraries." + }, + { + "name": "Query Documentation", + "description": "Retrieves and queries up-to-date documentation and code examples from Context7." + } + ], + "compatibility": { + "platforms": ["darwin", "win32", "linux"], + "runtimes": { + "node": ">=v18.0.0" + } + }, + "keywords": ["vibe-coding", "developer tools", "documentation", "context"], + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/upstash/context7.git" + } +} diff --git a/packages/mcp/package.json b/packages/mcp/package.json new file mode 100644 index 0000000..112c4d5 --- /dev/null +++ b/packages/mcp/package.json @@ -0,0 +1,62 @@ +{ + "name": "@upstash/context7-mcp", + "version": "3.2.3", + "mcpName": "io.github.upstash/context7", + "description": "MCP server for Context7", + "scripts": { + "build": "tsc && chmod 755 dist/index.js", + "test": "pnpm exec vitest run", + "typecheck": "tsc --noEmit", + "lint": "eslint .", + "lint:check": "eslint .", + "format": "prettier --write .", + "format:check": "prettier --check .", + "dev": "tsc --watch", + "start": "node dist/index.js --transport http", + "pack-mcpb": "pnpm install && pnpm run build && rm -rf node_modules && pnpm install --prod && cp mcpb/manifest.json manifest.json && cp mcpb/.mcpbignore .mcpbignore && cp ../../public/icon.png icon.png && mcpb validate manifest.json && mcpb pack . mcpb/context7.mcpb && rm manifest.json .mcpbignore icon.png && pnpm install" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/upstash/context7.git", + "directory": "packages/mcp" + }, + "keywords": [ + "modelcontextprotocol", + "mcp", + "context7", + "vibe-coding", + "developer tools", + "documentation", + "context" + ], + "author": "abdush", + "license": "MIT", + "type": "module", + "bin": { + "context7-mcp": "dist/index.js" + }, + "files": [ + "dist", + "LICENSE", + "README.md" + ], + "bugs": { + "url": "https://github.com/upstash/context7/issues" + }, + "homepage": "https://github.com/upstash/context7#readme", + "dependencies": { + "@modelcontextprotocol/sdk": "^1.29.0", + "@types/express": "^5.0.4", + "@upstash/redis": "^1.38.0", + "commander": "^13.1.0", + "express": "^5.1.0", + "jose": "^6.2.3", + "undici": "^6.26.0", + "zod": "^4.4.3" + }, + "devDependencies": { + "@types/node": "^25.0.3", + "typescript": "^5.8.2", + "vitest": "^4.1.9" + } +} diff --git a/packages/mcp/prettier.config.mjs b/packages/mcp/prettier.config.mjs new file mode 100644 index 0000000..206e41e --- /dev/null +++ b/packages/mcp/prettier.config.mjs @@ -0,0 +1,13 @@ +/** + * @type {import('prettier').Config} + */ +const config = { + endOfLine: "lf", + singleQuote: false, + tabWidth: 2, + trailingComma: "es5", + printWidth: 100, + arrowParens: "always", +}; + +export default config; diff --git a/packages/mcp/schema/context7.json b/packages/mcp/schema/context7.json new file mode 100644 index 0000000..606c4f2 --- /dev/null +++ b/packages/mcp/schema/context7.json @@ -0,0 +1,130 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://context7.com/schema/context7.json", + "title": "Context7 Configuration Schema", + "description": "Configuration file for Context7 project parsing and documentation generation", + "type": "object", + "properties": { + "projectTitle": { + "type": "string", + "description": "The display name for your project in Context7. This overrides the default repository name.", + "minLength": 1, + "maxLength": 100, + "examples": ["Upstash Ratelimit", "Next.js", "React Query"] + }, + "description": { + "type": "string", + "description": "A brief description of what your library does. This helps coding agents understand the purpose of your project.", + "minLength": 10, + "maxLength": 200, + "examples": [ + "Ratelimiting library based on Upstash Redis", + "The React Framework for Production", + "Powerful data synchronization for React" + ] + }, + "folders": { + "type": "array", + "description": "Specific folder paths to include when parsing documentation. If empty, Context7 will scan the entire repository. Supports regex patterns and requires full paths.", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true, + "default": [], + "examples": [ + ["docs", "guides", "examples"], + ["documentation/**"], + ["api-reference", "tutorials/*"] + ] + }, + "excludeFolders": { + "type": "array", + "description": "Folder paths to exclude from documentation parsing. Supports regex patterns and requires full paths.", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true, + "default": [], + "examples": [ + ["src", "build", "node_modules"], + ["**/test/**", "**/tests/**"], + ["legacy/*", "archive"] + ] + }, + "excludeFiles": { + "type": "array", + "description": "Specific file names to exclude from documentation parsing. Only include the filename (not the path). Regex patterns are not supported.", + "items": { + "type": "string", + "minLength": 1, + "pattern": "^[^/\\\\]+$" + }, + "uniqueItems": true, + "default": [], + "examples": [ + ["CHANGELOG.md", "LICENSE"], + ["README-dev.md", "CONTRIBUTING.md"], + ["package.json", "tsconfig.json"] + ] + }, + "rules": { + "type": "array", + "description": "Best practices or important guidelines that coding agents should follow when using your library. These appear as recommendations in the documentation context.", + "items": { + "type": "string", + "minLength": 5, + "maxLength": 200 + }, + "default": [], + "examples": [ + ["Always use TypeScript for better type safety"], + ["Use Upstash Redis as a database", "Use single region set up"], + ["Import components from the main package", "Follow the naming conventions"] + ] + }, + "previousVersions": { + "type": "array", + "description": "Information about previous versions of your library that should also be available in Context7.", + "items": { + "type": "object", + "properties": { + "tag": { + "type": "string", + "description": "The Git tag or version identifier", + "pattern": "^v?\\d+\\.\\d+\\.\\d+", + "examples": ["v1.2.1", "2.0.0", "v3.1.0-beta.1"] + }, + "title": { + "type": "string", + "description": "Human-readable version name", + "minLength": 1, + "maxLength": 50, + "examples": ["version 1.2.1", "Legacy Version", "Beta Release"] + } + }, + "required": ["tag", "title"], + "additionalProperties": false + }, + "default": [] + } + }, + "additionalProperties": false, + "examples": [ + { + "projectTitle": "Upstash Ratelimit", + "description": "Ratelimiting library based on Upstash Redis", + "folders": [], + "excludeFolders": ["src"], + "excludeFiles": [], + "rules": ["Use Upstash Redis as a database", "Use single region set up"], + "previousVersions": [ + { + "tag": "v1.2.1", + "title": "version 1.2.1" + } + ] + } + ] +} diff --git a/packages/mcp/smithery.yaml b/packages/mcp/smithery.yaml new file mode 100644 index 0000000..20eaeb1 --- /dev/null +++ b/packages/mcp/smithery.yaml @@ -0,0 +1,9 @@ +# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml + +startCommand: + type: http + configSchema: + # JSON Schema defining the configuration options for the MCP. + type: object + description: No configuration required + exampleConfig: {} diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts new file mode 100644 index 0000000..566bb38 --- /dev/null +++ b/packages/mcp/src/index.ts @@ -0,0 +1,655 @@ +#!/usr/bin/env node + +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; +import { + ListPromptsRequestSchema, + ListResourcesRequestSchema, + ListResourceTemplatesRequestSchema, +} from "@modelcontextprotocol/sdk/types.js"; +import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js"; +import { z } from "zod"; +import { searchLibraries, fetchLibraryContext } from "./lib/api.js"; +import type { ClientContext } from "./lib/types.js"; +import { formatSearchResults, extractClientInfoFromUserAgent } from "./lib/utils.js"; +import { isJWT, validateJWT } from "./lib/jwt.js"; +import express from "express"; +import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; +import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js"; +import { Command } from "commander"; +import { AsyncLocalStorage } from "async_hooks"; +import { randomUUID } from "node:crypto"; +import { createSessionStore } from "./lib/sessionStore.js"; +import { + SERVER_VERSION, + RESOURCE_URL, + AUTH_SERVER_URL, + OPENAI_APPS_CHALLENGE_TOKEN, +} from "./lib/constants.js"; +import { maybeElicitAuthSignIn } from "./lib/auth/auth-prompt.js"; +import { getClientIp } from "./lib/client-ip.js"; + +/** Default HTTP server port */ +const DEFAULT_PORT = 3000; + +// Parse CLI arguments using commander +const program = new Command() + .version(SERVER_VERSION, "-v, --version", "output the current version") + .option("--transport ", "transport type", "stdio") + .option("--port ", "port for HTTP transport", DEFAULT_PORT.toString()) + .option("--api-key ", "API key for authentication (or set CONTEXT7_API_KEY env var)") + .allowUnknownOption() // let MCP Inspector / other wrappers pass through extra flags + .parse(process.argv); + +const cliOptions = program.opts<{ + transport: string; + port: string; + apiKey?: string; +}>(); + +// Validate transport option +const allowedTransports = ["stdio", "http"]; +if (!allowedTransports.includes(cliOptions.transport)) { + console.error( + `Invalid --transport value: '${cliOptions.transport}'. Must be one of: stdio, http.` + ); + process.exit(1); +} + +// Transport configuration +const TRANSPORT_TYPE = (cliOptions.transport || "stdio") as "stdio" | "http"; + +// Disallow incompatible flags based on transport +const passedPortFlag = process.argv.includes("--port"); +const passedApiKeyFlag = process.argv.includes("--api-key"); + +if (TRANSPORT_TYPE === "http" && passedApiKeyFlag) { + console.error( + "The --api-key flag is not allowed when using --transport http. Use header-based auth at the HTTP layer instead." + ); + process.exit(1); +} + +if (TRANSPORT_TYPE === "stdio" && passedPortFlag) { + console.error("The --port flag is not allowed when using --transport stdio."); + process.exit(1); +} + +// HTTP port configuration +const CLI_PORT = (() => { + const parsed = parseInt(cliOptions.port, 10); + return isNaN(parsed) ? undefined : parsed; +})(); + +const requestContext = new AsyncLocalStorage(); + +// Global state for stdio mode only +let stdioApiKey: string | undefined; +let stdioClientInfo: { ide?: string; version?: string } | undefined; +// One session ID per stdio process. +let stdioSessionId: string | undefined; + +/** + * Get the effective client context + */ +function getClientContext(): ClientContext { + const ctx = requestContext.getStore(); + + // HTTP mode: context is fully populated from request + if (ctx) { + return ctx; + } + + // stdio mode: use globals + return { + apiKey: stdioApiKey, + clientInfo: stdioClientInfo, + transport: "stdio", + sessionId: stdioSessionId, + }; +} + +function createMcpServer() { + const server = new McpServer( + { + name: "Context7", + version: SERVER_VERSION, + websiteUrl: "https://context7.com", + description: + "Context7 provides up-to-date documentation and code examples for libraries and frameworks.", + icons: [ + { + src: "https://context7.com/context7-icon-green.png", + mimeType: "image/png", + }, + ], + }, + { + instructions: `Use this server to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs. + +Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.`, + } + ); + + server.registerTool( + "resolve-library-id", + { + title: "Resolve Context7 Library ID", + description: `Resolves a package/product name to a Context7-compatible library ID and returns matching libraries. + +You MUST call this function before 'Query Documentation' tool to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. + +Each result includes: +- Library ID: Context7-compatible identifier (format: /org/project) +- Name: Library or package name +- Description: Short summary +- Code Snippets: Number of available code examples +- Source Reputation: Authority indicator (High, Medium, Low, or Unknown) +- Benchmark Score: Quality indicator (100 is the highest score) +- Versions: List of versions if available. Use one of those versions if the user provides a version in their query. The format of the version is /org/project/version. + +For best results, select libraries based on name match, source reputation, snippet coverage, benchmark score, and relevance to your use case. + +Selection Process: +1. Analyze the query to understand what library/package the user is looking for +2. Return the most relevant match based on: +- Name similarity to the query (exact matches prioritized) +- Description relevance to the query's intent +- Documentation coverage (prioritize libraries with higher Code Snippet counts) +- Source reputation (consider libraries with High or Medium reputation more authoritative) +- Benchmark Score: Quality indicator (100 is the highest score) + +Response Format: +- Return the selected library ID in a clearly marked section +- Provide a brief explanation for why this library was chosen +- If multiple good matches exist, acknowledge this but proceed with the most relevant one +- If no good matches exist, clearly state this and suggest query refinements + +For ambiguous queries, request clarification before proceeding with a best-guess match. + +IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.`, + inputSchema: { + query: z + .string() + .describe( + "The question or task you need help with. This is used to rank library results by relevance to what the user is trying to accomplish. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query." + ), + libraryName: z + .string() + .describe( + "Library name to search for and retrieve a Context7-compatible library ID. Use the official library name with proper punctuation — e.g., 'Next.js' instead of 'nextjs', 'Customer.io' instead of 'customerio', 'Three.js' instead of 'threejs'." + ), + }, + annotations: { + readOnlyHint: true, + destructiveHint: false, + openWorldHint: true, + idempotentHint: true, + }, + }, + async ({ query, libraryName }: { query: string; libraryName: string }) => { + const ctx = getClientContext(); + const searchResponse = await searchLibraries(query, libraryName, ctx); + + if (!searchResponse.results || searchResponse.results.length === 0) { + const text = searchResponse.error ?? "No libraries found matching the provided name."; + maybeElicitAuthSignIn(server, ctx); + return { + content: [ + { + type: "text", + text, + }, + ], + }; + } + + const resultsText = formatSearchResults(searchResponse); + const responseText = `Available Libraries:\n\n${resultsText}`; + maybeElicitAuthSignIn(server, ctx); + return { + content: [ + { + type: "text", + text: responseText, + }, + ], + }; + } + ); + + server.registerTool( + "query-docs", + { + title: "Query Documentation", + description: `Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework. + +You must call 'Resolve Context7 Library ID' tool first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. + +Do not call this tool more than 3 times per question.`, + inputSchema: { + libraryId: z + .string() + .describe( + "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolve-library-id' or directly from user query in the format '/org/project' or '/org/project/version'." + ), + query: z + .string() + .describe( + "The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query." + ), + }, + annotations: { + readOnlyHint: true, + destructiveHint: false, + openWorldHint: true, + idempotentHint: true, + }, + }, + async ({ query, libraryId }: { query: string; libraryId: string }) => { + const ctx = getClientContext(); + const response = await fetchLibraryContext({ query, libraryId }, ctx); + maybeElicitAuthSignIn(server, ctx); + return { + content: [ + { + type: "text", + text: response.data, + }, + ], + }; + } + ); + + server.server.registerCapabilities({ prompts: {}, resources: {} }); + server.server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] })); + server.server.setRequestHandler(ListResourcesRequestSchema, async () => ({ + resources: [], + })); + server.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({ + resourceTemplates: [], + })); + + return server; +} + +// Map of canonical arg name -> hallucinated aliases that should be rewritten +// to it. LLM clients often echo phrasing from tool descriptions instead of +// the literal schema keys, which trips Zod validation before the tool runs. +type AliasMap = Record; + +const GLOBAL_ALIASES: AliasMap = { + query: ["userQuery", "question"], +}; + +// Tool-scoped aliases, for keys that are canonical on one tool but a +// hallucination on another (e.g. `libraryName` is canonical for +// `resolve-library-id`, so we only rewrite it on `query-docs` calls). +const TOOL_ALIASES: Record = { + "query-docs": { + libraryId: ["context7CompatibleLibraryID", "libraryID", "libraryName"], + }, +}; + +function applyAliases(args: Record, aliases: AliasMap): void { + for (const [canonical, alternatives] of Object.entries(aliases)) { + if (canonical in args) continue; + for (const alt of alternatives) { + if (alt in args) { + args[canonical] = args[alt]; + delete args[alt]; + break; + } + } + } +} + +// Install BEFORE `server.connect(transport)`: the SDK's `Protocol.connect()` +// captures the existing `onmessage` and chains its dispatch handler over it, +// so our hook runs first on every incoming JSON-RPC message. +function installTransportArgAliasing(transport: Transport): void { + transport.onmessage = (message) => { + const msg = message as { + method?: string; + params?: { name?: string; arguments?: unknown }; + }; + if (msg.method !== "tools/call") return; + const args = msg.params?.arguments; + if (!args || typeof args !== "object") return; + const argsRecord = args as Record; + + applyAliases(argsRecord, GLOBAL_ALIASES); + + const toolName = msg.params?.name; + if (toolName && toolName in TOOL_ALIASES) { + applyAliases(argsRecord, TOOL_ALIASES[toolName]); + } + }; +} + +async function main() { + const transportType = TRANSPORT_TYPE; + + if (transportType === "http") { + const initialPort = CLI_PORT ?? DEFAULT_PORT; + + const app = express(); + app.use(express.json()); + + app.use((req: express.Request, res: express.Response, next: express.NextFunction) => { + res.setHeader("Access-Control-Allow-Origin", "*"); + res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS,DELETE"); + res.setHeader( + "Access-Control-Allow-Headers", + "Content-Type, MCP-Session-Id, MCP-Protocol-Version, X-Context7-API-Key, Context7-API-Key, X-API-Key, Authorization" + ); + res.setHeader("Access-Control-Expose-Headers", "MCP-Session-Id"); + + if (req.method === "OPTIONS") { + res.sendStatus(200); + return; + } + next(); + }); + + const extractHeaderValue = (value: string | string[] | undefined): string | undefined => { + if (!value) return undefined; + return typeof value === "string" ? value : value[0]; + }; + + const extractBearerToken = (authHeader: string | string[] | undefined): string | undefined => { + const header = extractHeaderValue(authHeader); + if (!header) return undefined; + + if (header.startsWith("Bearer ")) { + return header.substring(7).trim(); + } + + return header; + }; + + const extractApiKey = (req: express.Request): string | undefined => { + return ( + extractBearerToken(req.headers.authorization) || + extractHeaderValue(req.headers["context7-api-key"]) || + extractHeaderValue(req.headers["x-api-key"]) || + extractHeaderValue(req.headers["context7_api_key"]) || + extractHeaderValue(req.headers["x_api_key"]) + ); + }; + + const sessionStore = createSessionStore(); + + const handleMcpRequest = async ( + req: express.Request, + res: express.Response, + requireAuth: boolean + ) => { + // Reject GET requests — sessions are tracked in Redis, but this server does not send + // server-initiated notifications, so SSE streams serve no purpose and cause mass NGINX + // timeouts. Returning 405 is spec-compliant per MCP StreamableHTTP (2025-03-26). + if (req.method === "GET") { + return res.status(405).json({ + jsonrpc: "2.0", + error: { code: -32000, message: "Server does not support GET requests" }, + id: null, + }); + } + + try { + const apiKey = extractApiKey(req); + const resourceUrl = RESOURCE_URL; + const baseUrl = new URL(resourceUrl).origin; + + // OAuth discovery info header, used by MCP clients to discover the authorization server + res.set( + "WWW-Authenticate", + `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource"` + ); + + if (requireAuth) { + if (!apiKey) { + return res.status(401).json({ + jsonrpc: "2.0", + error: { + code: -32001, + message: "Authentication required. Please authenticate to use this MCP server.", + }, + id: null, + }); + } + + if (isJWT(apiKey)) { + const validationResult = await validateJWT(apiKey); + if (!validationResult.valid) { + return res.status(401).json({ + jsonrpc: "2.0", + error: { + code: -32001, + message: validationResult.error || "Invalid token. Please re-authenticate.", + }, + id: null, + }); + } + } + } + + const context: ClientContext = { + clientIp: getClientIp(req), + apiKey: apiKey, + clientInfo: extractClientInfoFromUserAgent(req.headers["user-agent"]), + transport: "http", + }; + + const sessionId = extractHeaderValue(req.headers["mcp-session-id"]); + + if (req.method === "DELETE") { + if (!sessionId) { + return res.status(400).json({ + jsonrpc: "2.0", + error: { code: -32000, message: "Bad Request: No valid session ID provided" }, + id: null, + }); + } + await sessionStore.delete(sessionId); + return res.status(200).end(); + } + + let effectiveSessionId: string; + if (!sessionId && req.method === "POST" && isInitializeRequest(req.body)) { + effectiveSessionId = randomUUID(); + await sessionStore.create(effectiveSessionId); + res.setHeader("mcp-session-id", effectiveSessionId); + } else if (sessionId && req.method === "POST" && !isInitializeRequest(req.body)) { + const sessionExists = await sessionStore.refresh(sessionId); + if (!sessionExists) { + // Per MCP Streamable HTTP spec: 404 signals to the client that the session + // has been terminated/expired, so it should re-initialize with a fresh InitializeRequest. + return res.status(404).json({ + jsonrpc: "2.0", + error: { + code: -32000, + message: "Session not found or expired. Please re-initialize.", + }, + id: null, + }); + } + effectiveSessionId = sessionId; + } else { + return res.status(400).json({ + jsonrpc: "2.0", + error: { code: -32000, message: "Bad Request: No valid session ID provided" }, + id: null, + }); + } + + context.sessionId = effectiveSessionId; + + // sessionIdGenerator is undefined because session lifecycle (create/refresh/delete) + // is owned by the route handler above and persisted in Redis, not by the SDK transport. + // + // Use SSE responses for tool calls (enableJsonResponse: false). The SDK then + // flushes response headers immediately after parsing the request rather than + // buffering until the tool returns. This is required for long-running tools + // because some MCP HTTP clients cap the underlying fetch at 60s waiting for + // headers, even though the per-tool timeout is much higher. + const transport = new StreamableHTTPServerTransport({ + sessionIdGenerator: undefined, + enableJsonResponse: false, + }); + + const server = createMcpServer(); + res.on("close", () => { + transport.close(); + server.close(); + }); + + installTransportArgAliasing(transport); + await server.connect(transport); + + await requestContext.run(context, async () => { + await transport.handleRequest(req, res, req.body); + }); + } catch (error) { + console.error("Error handling MCP request:", error); + if (!res.headersSent) { + res.status(500).json({ + jsonrpc: "2.0", + error: { code: -32603, message: "Internal server error" }, + id: null, + }); + } + } + }; + + // Anonymous access endpoint - no authentication required + app.all("/mcp", async (req, res) => { + await handleMcpRequest(req, res, false); + }); + + // OAuth-protected endpoint - requires authentication + app.all("/mcp/oauth", async (req, res) => { + await handleMcpRequest(req, res, true); + }); + + app.get("/ping", (_req: express.Request, res: express.Response) => { + res.json({ status: "ok", message: "pong" }); + }); + + // OAuth 2.0 Protected Resource Metadata (RFC 9728) + // Used by MCP clients to discover the authorization server + app.get( + "/.well-known/oauth-protected-resource", + (_req: express.Request, res: express.Response) => { + res.json({ + resource: RESOURCE_URL, + authorization_servers: [AUTH_SERVER_URL], + scopes_supported: ["profile", "email"], + bearer_methods_supported: ["header"], + }); + } + ); + + app.get( + "/.well-known/oauth-authorization-server", + async (_req: express.Request, res: express.Response) => { + const authServerUrl = AUTH_SERVER_URL; + + try { + const response = await fetch(`${authServerUrl}/.well-known/oauth-authorization-server`); + if (!response.ok) { + console.error("[OAuth] Upstream error:", response.status); + return res.status(response.status).json({ + error: "upstream_error", + message: "Failed to fetch authorization server metadata", + }); + } + const metadata = await response.json(); + res.json(metadata); + } catch (error) { + console.error("[OAuth] Error fetching OAuth metadata:", error); + res.status(502).json({ + error: "proxy_error", + message: "Failed to proxy authorization server metadata", + }); + } + } + ); + + // OpenAI Apps SDK domain verification challenge + app.get( + "/.well-known/openai-apps-challenge", + (_req: express.Request, res: express.Response) => { + if (!OPENAI_APPS_CHALLENGE_TOKEN) { + return res.status(404).json({ + error: "not_found", + message: "Endpoint not found.", + }); + } + res.type("text/plain").send(OPENAI_APPS_CHALLENGE_TOKEN); + } + ); + + // Catch-all 404 handler - must be after all other routes + app.use((_req: express.Request, res: express.Response) => { + res.status(404).json({ + error: "not_found", + message: "Endpoint not found. Use /mcp for MCP protocol communication.", + }); + }); + + const startServer = (port: number, maxAttempts = 10) => { + const httpServer = app.listen(port); + + httpServer.once("error", (err: NodeJS.ErrnoException) => { + if (err.code === "EADDRINUSE" && port < initialPort + maxAttempts) { + console.warn(`Port ${port} is in use, trying port ${port + 1}...`); + startServer(port + 1, maxAttempts); + } else { + console.error(`Failed to start server: ${err.message}`); + process.exit(1); + } + }); + + httpServer.once("listening", () => { + console.error( + `Context7 Documentation MCP Server v${SERVER_VERSION} running on HTTP at http://localhost:${port}/mcp` + ); + }); + }; + + startServer(initialPort); + } else { + stdioApiKey = cliOptions.apiKey || process.env.CONTEXT7_API_KEY; + stdioSessionId = randomUUID(); + + process.stdin.on("end", () => process.exit(0)); + process.stdin.on("close", () => process.exit(0)); + process.on("SIGHUP", () => process.exit(0)); + + const transport = new StdioServerTransport(); + const server = createMcpServer(); + + // Capture client info from MCP initialize handshake (stdio only — HTTP + // mode plumbs client info through requestContext per request). + server.server.oninitialized = () => { + const clientVersion = server.server.getClientVersion(); + if (clientVersion) { + stdioClientInfo = { + ide: clientVersion.name, + version: clientVersion.version, + }; + } + }; + + installTransportArgAliasing(transport); + await server.connect(transport); + + console.error(`Context7 Documentation MCP Server v${SERVER_VERSION} running on stdio`); + } +} + +main().catch((error) => { + console.error("Fatal error in main():", error); + process.exit(1); +}); diff --git a/packages/mcp/src/lib/api.ts b/packages/mcp/src/lib/api.ts new file mode 100644 index 0000000..6bcd450 --- /dev/null +++ b/packages/mcp/src/lib/api.ts @@ -0,0 +1,175 @@ +import { SearchResponse, ContextRequest, ContextResponse, ClientContext } from "./types.js"; +import { generateHeaders } from "./encryption.js"; +import { Agent, ProxyAgent, setGlobalDispatcher } from "undici"; +import { CONTEXT7_API_BASE_URL } from "./constants.js"; +import { readFileSync } from "fs"; +import tls from "tls"; + +/** + * Parses error response from the Context7 API + * Extracts the server's error message, falling back to status-based messages if parsing fails + * @param response The fetch Response object + * @param apiKey Optional API key (used for fallback messages) + * @returns Error message string + */ +async function parseErrorResponse(response: Response, apiKey?: string): Promise { + try { + const json = (await response.json()) as { message?: string }; + if (json.message) { + return json.message; + } + } catch { + // JSON parsing failed, fall through to default + } + + const status = response.status; + if (status === 429) { + return apiKey + ? "Rate limited or quota exceeded. Upgrade your plan at https://context7.com/plans for higher limits." + : "Rate limited or quota exceeded. Create a free API key at https://context7.com/dashboard for higher limits."; + } + if (status === 404) { + return "The library you are trying to access does not exist. Please try with a different library ID."; + } + if (status === 401) { + return "Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix."; + } + return `Request failed with status ${status}. Please try again later.`; +} + +const PROXY_URL: string | null = + process.env.HTTPS_PROXY ?? + process.env.https_proxy ?? + process.env.HTTP_PROXY ?? + process.env.http_proxy ?? + null; + +const CUSTOM_CA_CERTS: string | undefined = process.env.NODE_EXTRA_CA_CERTS; + +export function getDefaultCACertificates(): string[] { + if (typeof tls.getCACertificates === "function") { + return tls.getCACertificates("default"); + } + + return [...tls.rootCertificates]; +} + +export function loadCustomCACerts(customCACertsPath = CUSTOM_CA_CERTS): string[] | undefined { + if (!customCACertsPath) return undefined; + try { + const customCa = readFileSync(customCACertsPath, "utf-8"); + return [...getDefaultCACertificates(), customCa]; + } catch (error) { + console.error( + `[Context7] Failed to load custom CA certificates from ${customCACertsPath}:`, + error + ); + return undefined; + } +} + +if (PROXY_URL && !PROXY_URL.startsWith("$") && /^(http|https):\/\//i.test(PROXY_URL)) { + try { + const ca = loadCustomCACerts(); + setGlobalDispatcher( + new ProxyAgent({ + uri: PROXY_URL, + ...(ca ? { requestTls: { ca }, proxyTls: { ca } } : {}), + }) + ); + } catch (error) { + console.error( + `[Context7] Failed to configure proxy agent for provided proxy URL: ${PROXY_URL}:`, + error + ); + } +} else if (CUSTOM_CA_CERTS) { + const ca = loadCustomCACerts(); + if (ca) { + try { + setGlobalDispatcher(new Agent({ connect: { ca } })); + } catch (error) { + console.error(`[Context7] Failed to configure custom CA certificates:`, error); + } + } +} + +function readPromptSignal(response: Response, context: ClientContext): void { + if (response.headers.get("X-Context7-Auth-Prompt") === "1") { + context.shouldPrompt = true; + } +} + +/** + * Searches for libraries matching the given query + * @param query The user's question or task (used for LLM relevance ranking) + * @param libraryName The library name to search for in the database + * @param context Client context including IP, API key, and client info + * @returns Search results or error + */ +export async function searchLibraries( + query: string, + libraryName: string, + context: ClientContext = {} +): Promise { + try { + const url = new URL(`${CONTEXT7_API_BASE_URL}/v2/libs/search`); + url.searchParams.set("query", query); + url.searchParams.set("libraryName", libraryName); + + const headers = generateHeaders(context); + + const response = await fetch(url, { headers }); + readPromptSignal(response, context); + if (!response.ok) { + const errorMessage = await parseErrorResponse(response, context.apiKey); + console.error(errorMessage); + return { results: [], error: errorMessage }; + } + const searchData = await response.json(); + return searchData as SearchResponse; + } catch (error) { + const errorMessage = `Error searching libraries: ${error}`; + console.error(errorMessage); + return { results: [], error: errorMessage }; + } +} + +/** + * Fetches intelligent, reranked context for a natural language query + * @param request The context request parameters (query, libraryId) + * @param context Client context including IP, API key, and client info + * @returns Context response with data + */ +export async function fetchLibraryContext( + request: ContextRequest, + context: ClientContext = {} +): Promise { + try { + const url = new URL(`${CONTEXT7_API_BASE_URL}/v2/context`); + url.searchParams.set("query", request.query); + url.searchParams.set("libraryId", request.libraryId); + + const headers = generateHeaders(context); + + const response = await fetch(url, { headers }); + readPromptSignal(response, context); + if (!response.ok) { + const errorMessage = await parseErrorResponse(response, context.apiKey); + console.error(errorMessage); + return { data: errorMessage }; + } + + const text = await response.text(); + if (!text) { + return { + data: "Documentation not found or not finalized for this library. This might have happened because you used an invalid Context7-compatible library ID. To get a valid Context7-compatible library ID, use the 'resolve-library-id' with the package name you wish to retrieve documentation for.", + }; + } + return { data: text }; + } catch (error) { + const errorMessage = `Error fetching library context. Please try again later. ${error}`; + console.error(errorMessage); + return { data: errorMessage }; + } +} diff --git a/packages/mcp/src/lib/auth/auth-prompt.ts b/packages/mcp/src/lib/auth/auth-prompt.ts new file mode 100644 index 0000000..319c225 --- /dev/null +++ b/packages/mcp/src/lib/auth/auth-prompt.ts @@ -0,0 +1,91 @@ +import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import type { ClientContext } from "../types.js"; + +function clientFlagForCli(ide: string | undefined): string { + if (!ide) return ""; + const lower = ide.toLowerCase(); + if (lower.includes("cursor")) return "--cursor"; + if (lower.includes("claude")) return "--claude"; + if (lower.includes("codex")) return "--codex"; + if (lower.includes("opencode")) return "--opencode"; + if (lower.includes("gemini")) return "--gemini"; + return ""; +} + +function buildAuthCommand( + clientIde: string | undefined, + transport: "stdio" | "http" | undefined +): string { + const flag = clientFlagForCli(clientIde); + const transportFlag = transport === "stdio" ? " --stdio" : ""; + return flag + ? `npx ctx7 setup ${flag} --mcp${transportFlag} -y` + : `npx ctx7 setup --mcp${transportFlag}`; +} + +function buildElicitMessage( + clientIde: string | undefined, + transport: "stdio" | "http" | undefined +): string { + const command = buildAuthCommand(clientIde, transport); + return [ + "You're using Context7 anonymously. To unlock free higher rate limits, run this in your terminal:", + "", + ` ${command}`, + "", + "It opens your browser, signs you in, and writes credentials into your MCP client config.", + "After it finishes, disable then re-enable the Context7 MCP server in your editor so the new credentials take effect.", + ].join("\n"); +} + +// User-facing strings double as enum const values: keeps the schema in the +// simpler `enum: [...]` shape, which clients render more reliably than +// `oneOf` with separate `const`/`title`. +const CHOICE_RUN_SETUP = "I'll run the command to sign in"; +const CHOICE_STAY_ANON = "Continue anonymously with smaller limits"; + +/** + * Fires a form-mode elicitation that surfaces a sign-in nudge in the client UI + * when the backend has signaled (via `X-Context7-Auth-Prompt: 1`, captured on + * `ctx.shouldPrompt` in api.ts) that the anonymous caller should be prompted + * to authenticate. + * + * The message is delivered out-of-band to the human via the client, not into + * the tool result the LLM reads, so it does not trip prompt-injection guards. + * + * The backend owns how often this fires: it sets the header at most once per + * MCP session, so the server holds no suppression state — it simply shows the + * dialog whenever the header is present. The command itself is shown in the + * dialog message for the user to copy; the server does not attempt to drive + * the client to run it. + * + * No-op for authenticated callers, when the signal wasn't set, or when the + * client did not advertise the `elicitation` capability. Fire-and-forget: + * never blocks or fails the surrounding tool response. + */ +export function maybeElicitAuthSignIn(server: McpServer, ctx: ClientContext): void { + if (ctx.apiKey || !ctx.shouldPrompt) return; + if (!server.server.getClientCapabilities()?.elicitation) return; + + void server.server + .elicitInput({ + message: buildElicitMessage(ctx.clientInfo?.ide, ctx.transport), + requestedSchema: { + type: "object", + properties: { + choice: { + type: "string", + title: "How would you like to continue?", + enum: [CHOICE_RUN_SETUP, CHOICE_STAY_ANON], + default: CHOICE_RUN_SETUP, + }, + }, + required: ["choice"], + }, + }) + .catch(() => { + // Client may not support elicitation despite the capability flag, or + // the session may have closed before the user responded. Either way, + // a missed nudge should never affect the tool result. + }); +} diff --git a/packages/mcp/src/lib/client-ip.ts b/packages/mcp/src/lib/client-ip.ts new file mode 100644 index 0000000..5c8ab2d --- /dev/null +++ b/packages/mcp/src/lib/client-ip.ts @@ -0,0 +1,78 @@ +import type express from "express"; + +function stripIpv4MappedPrefix(ip: string): string { + return ip.replace(/^::ffff:/i, ""); +} + +/** + * Returns true for RFC1918, CGNAT, loopback, link-local, and IPv6 private ranges. + */ +export function isPrivateOrLocalIp(ip: string): boolean { + const plainIp = stripIpv4MappedPrefix(ip).toLowerCase(); + + if (plainIp.includes(".")) { + return ( + plainIp.startsWith("10.") || + plainIp.startsWith("192.168.") || + /^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(plainIp) || + /^100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\./.test(plainIp) || + plainIp.startsWith("127.") || + plainIp.startsWith("169.254.") + ); + } + + // ::1 loopback in any textual form (e.g. "0::1", "0:0:0:0:0:0:0:1") + if (/^[0:]+1$/.test(plainIp)) { + return true; + } + + // First hextets in fe80::/10 and fc00::/7 start with a non-zero digit, so a + // valid textual form always spells out all 4 digits. + + // fe80::/10 link-local + if (/^fe[89ab][0-9a-f]:/.test(plainIp)) { + return true; + } + + // fc00::/7 unique local + if (/^f[cd][0-9a-f]{2}:/.test(plainIp)) { + return true; + } + + return false; +} + +function pickClientIpFromForwardedList(ipList: string[]): string | undefined { + for (const ip of ipList) { + const plainIp = stripIpv4MappedPrefix(ip); + if (!isPrivateOrLocalIp(plainIp)) { + return plainIp; + } + } + + if (ipList.length === 0) { + return undefined; + } + + return stripIpv4MappedPrefix(ipList[0]); +} + +/** + * Extract client IP address from request headers. + * Handles X-Forwarded-For header for proxied requests. + */ +export function getClientIp(req: express.Request): string | undefined { + const forwardedFor = req.headers["x-forwarded-for"] || req.headers["X-Forwarded-For"]; + + if (forwardedFor) { + const ips = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor; + const ipList = ips.split(",").map((ip) => ip.trim()); + return pickClientIpFromForwardedList(ipList); + } + + if (req.socket?.remoteAddress) { + return stripIpv4MappedPrefix(req.socket.remoteAddress); + } + + return undefined; +} diff --git a/packages/mcp/src/lib/constants.ts b/packages/mcp/src/lib/constants.ts new file mode 100644 index 0000000..fa99be6 --- /dev/null +++ b/packages/mcp/src/lib/constants.ts @@ -0,0 +1,22 @@ +import { readFileSync } from "fs"; +import { fileURLToPath } from "url"; +import { dirname, join } from "path"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8")); + +export const SERVER_VERSION: string = pkg.version; + +const CONTEXT7_BASE_URL = "https://context7.com"; +const MCP_RESOURCE_URL = "https://mcp.context7.com"; + +export const CLERK_DOMAIN = "clerk.context7.com"; +export const CONTEXT7_API_BASE_URL = process.env.CONTEXT7_API_URL || `${CONTEXT7_BASE_URL}/api`; +export const RESOURCE_URL = process.env.RESOURCE_URL || MCP_RESOURCE_URL; +export const AUTH_SERVER_URL = process.env.AUTH_SERVER_URL || CONTEXT7_BASE_URL; + +// Enterprise-Managed Auth (id-jag): access tokens minted by the Context7 +// authorization server, validated against its public JWKS. +export const EMA_ISSUER = AUTH_SERVER_URL; +export const EMA_JWKS_URL = process.env.EMA_JWKS_URL || `${CONTEXT7_API_BASE_URL}/oauth/ema-jwks`; +export const OPENAI_APPS_CHALLENGE_TOKEN = process.env.OPENAI_APPS_CHALLENGE_TOKEN; diff --git a/packages/mcp/src/lib/encryption.ts b/packages/mcp/src/lib/encryption.ts new file mode 100644 index 0000000..91ceb1f --- /dev/null +++ b/packages/mcp/src/lib/encryption.ts @@ -0,0 +1,62 @@ +import { createCipheriv, randomBytes } from "crypto"; +import { SERVER_VERSION } from "./constants.js"; +import type { ClientContext } from "./types.js"; + +const DEFAULT_ENCRYPTION_KEY = "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"; +const ENCRYPTION_KEY = process.env.CLIENT_IP_ENCRYPTION_KEY || DEFAULT_ENCRYPTION_KEY; +const ALGORITHM = "aes-256-cbc"; + +function validateEncryptionKey(key: string): boolean { + // Must be exactly 64 hex characters (32 bytes) + return /^[0-9a-fA-F]{64}$/.test(key); +} + +function encryptClientIp(clientIp: string): string { + if (!validateEncryptionKey(ENCRYPTION_KEY)) { + console.error("Invalid encryption key format. Must be 64 hex characters."); + return clientIp; // Fallback to unencrypted + } + + try { + const iv = randomBytes(16); + const cipher = createCipheriv(ALGORITHM, Buffer.from(ENCRYPTION_KEY, "hex"), iv); + let encrypted = cipher.update(clientIp, "utf8", "hex"); + encrypted += cipher.final("hex"); + return iv.toString("hex") + ":" + encrypted; + } catch (error) { + console.error("Error encrypting client IP:", error); + return clientIp; // Fallback to unencrypted + } +} + +/** + * Generate headers for Context7 API requests. + * Handles client IP encryption, authentication, and telemetry headers. + */ +export function generateHeaders(context: ClientContext): Record { + const headers: Record = { + "X-Context7-Source": "mcp-server", + "X-Context7-Server-Version": SERVER_VERSION, + }; + + if (context.clientIp) { + headers["mcp-client-ip"] = encryptClientIp(context.clientIp); + } + if (context.sessionId) { + headers["mcp-session-id"] = context.sessionId; + } + if (context.apiKey) { + headers["Authorization"] = `Bearer ${context.apiKey}`; + } + if (context.clientInfo?.ide) { + headers["X-Context7-Client-IDE"] = context.clientInfo.ide; + } + if (context.clientInfo?.version) { + headers["X-Context7-Client-Version"] = context.clientInfo.version; + } + if (context.transport) { + headers["X-Context7-Transport"] = context.transport; + } + + return headers; +} diff --git a/packages/mcp/src/lib/jwt.ts b/packages/mcp/src/lib/jwt.ts new file mode 100644 index 0000000..a1bce84 --- /dev/null +++ b/packages/mcp/src/lib/jwt.ts @@ -0,0 +1,120 @@ +import * as jose from "jose"; +import { + CLERK_DOMAIN, + CONTEXT7_API_BASE_URL, + EMA_ISSUER, + EMA_JWKS_URL, + RESOURCE_URL, +} from "./constants.js"; + +const CLERK_ISSUER = `https://${CLERK_DOMAIN}`; +const clerkJwks = jose.createRemoteJWKSet(new URL(`https://${CLERK_DOMAIN}/.well-known/jwks.json`)); + +const emaJwks = jose.createRemoteJWKSet(new URL(EMA_JWKS_URL)); + +const ENTRA_V2_ISSUER_RE = /^https:\/\/login\.microsoftonline\.com\/[0-9a-f-]{36}\/v2\.0$/; + +const jwksByTenant = new Map>(); +function entraJwks(tenantId: string) { + let jwks = jwksByTenant.get(tenantId); + if (!jwks) { + jwks = jose.createRemoteJWKSet( + new URL(`https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`) + ); + jwksByTenant.set(tenantId, jwks); + } + return jwks; +} + +interface EntraConfig { + teamspaceId: string; + tenantId: string; + requiredScope: string | null; +} + +const CONFIG_TTL_MS = 5 * 60 * 1000; +const configByAudience = new Map(); + +async function fetchEntraConfig(audience: string): Promise { + const now = Date.now(); + const cached = configByAudience.get(audience); + if (cached && cached.expiresAt > now) return cached.value; + + try { + const res = await fetch( + `${CONTEXT7_API_BASE_URL}/v2/entra/config/${encodeURIComponent(audience)}` + ); + if (res.ok) { + const value = (await res.json()) as EntraConfig; + configByAudience.set(audience, { value, expiresAt: now + CONFIG_TTL_MS }); + return value; + } + if (res.status === 404) { + // Authoritative "not configured" response — safe to cache the miss so we + // don't hammer the app on every token verification. + configByAudience.set(audience, { value: null, expiresAt: now + CONFIG_TTL_MS }); + return null; + } + } catch { + // Network or JSON parse error: transient. Fall through without caching so + // the next request retries. + } + return null; +} + +export interface JWTValidationResult { + valid: boolean; + error?: string; +} + +export function isJWT(token: string): boolean { + return token.split(".").length === 3; +} + +export async function validateJWT(token: string): Promise { + try { + const decoded = jose.decodeJwt(token); + const iss = typeof decoded.iss === "string" ? decoded.iss : ""; + + if (ENTRA_V2_ISSUER_RE.test(iss)) { + const audience = typeof decoded.aud === "string" ? decoded.aud : ""; + if (!audience) return { valid: false, error: "Missing audience" }; + + const config = await fetchEntraConfig(audience); + if (!config) return { valid: false, error: "Unknown audience" }; + + const { payload } = await jose.jwtVerify(token, entraJwks(config.tenantId), { + issuer: `https://login.microsoftonline.com/${config.tenantId}/v2.0`, + audience, + }); + + if (config.requiredScope) { + const scopes = String(payload.scp ?? "").split(" "); + if (!scopes.includes(config.requiredScope)) { + return { valid: false, error: "Missing required scope" }; + } + } + + return { valid: true }; + } + + if (iss === EMA_ISSUER) { + await jose.jwtVerify(token, emaJwks, { issuer: EMA_ISSUER, audience: RESOURCE_URL }); + return { valid: true }; + } + + await jose.jwtVerify(token, clerkJwks, { issuer: CLERK_ISSUER }); + return { valid: true }; + } catch (error) { + if (error instanceof jose.errors.JWTExpired) { + return { valid: false, error: "Token expired" }; + } + if (error instanceof jose.errors.JWTClaimValidationFailed) { + return { valid: false, error: "Invalid token claims" }; + } + if (error instanceof jose.errors.JWSSignatureVerificationFailed) { + return { valid: false, error: "Invalid signature" }; + } + return { valid: false, error: "Invalid token" }; + } +} diff --git a/packages/mcp/src/lib/redis.ts b/packages/mcp/src/lib/redis.ts new file mode 100644 index 0000000..c71bb0c --- /dev/null +++ b/packages/mcp/src/lib/redis.ts @@ -0,0 +1,17 @@ +import { Redis } from "@upstash/redis"; + +let cached: Redis | undefined; + +/** + * Returns the shared Upstash Redis client. Throws if credentials are missing. + */ +export function getRedis(): Redis { + if (cached) return cached; + if (!process.env.UPSTASH_REDIS_REST_URL || !process.env.UPSTASH_REDIS_REST_TOKEN) { + throw new Error( + "Upstash Redis credentials are required. Set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN." + ); + } + cached = Redis.fromEnv(); + return cached; +} diff --git a/packages/mcp/src/lib/sessionStore.ts b/packages/mcp/src/lib/sessionStore.ts new file mode 100644 index 0000000..e9a7cf5 --- /dev/null +++ b/packages/mcp/src/lib/sessionStore.ts @@ -0,0 +1,49 @@ +import { getRedis } from "./redis.js"; + +const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60; // 7 days +const REFRESH_THRESHOLD_SECONDS = 24 * 60 * 60; // 1 day — only extend TTL when below this +const SESSION_KEY_PREFIX = "#mcp#session#"; + +// Fail-open: log Redis errors and proceed. The session ID isn't an auth/authz +// primitive — only an opaque identifier for log correlation and spec compliance — +// so an unreachable Redis shouldn't block clients. Ghost sessions self-heal on +// the next refresh (returns false → client gets 404 → re-inits). +export function createSessionStore() { + const redis = getRedis(); + + const getSessionKey = (sessionId: string) => `${SESSION_KEY_PREFIX}${sessionId}`; + + return { + async create(sessionId: string) { + try { + await redis.set(getSessionKey(sessionId), "1", { ex: SESSION_TTL_SECONDS }); + } catch (err) { + console.error(`Error creating Redis session record ${sessionId}:`, err); + } + }, + + async refresh(sessionId: string) { + try { + // One TTL call tells us both whether the key exists AND how much time it has left. + // Only issue an EXPIRE write when the key is approaching expiry + const ttl = await redis.ttl(getSessionKey(sessionId)); + if (ttl < 0) return false; + if (ttl < REFRESH_THRESHOLD_SECONDS) { + await redis.expire(getSessionKey(sessionId), SESSION_TTL_SECONDS); + } + return true; + } catch (err) { + console.error(`Error refreshing Redis session record ${sessionId}:`, err); + return true; + } + }, + + async delete(sessionId: string) { + try { + await redis.del(getSessionKey(sessionId)); + } catch (err) { + console.error(`Error deleting Redis session record ${sessionId}:`, err); + } + }, + }; +} diff --git a/packages/mcp/src/lib/types.ts b/packages/mcp/src/lib/types.ts new file mode 100644 index 0000000..3b5a024 --- /dev/null +++ b/packages/mcp/src/lib/types.ts @@ -0,0 +1,47 @@ +export interface SearchResult { + id: string; + title: string; + description: string; + branch: string; + lastUpdateDate: string; + state: DocumentState; + totalTokens: number; + totalSnippets: number; + stars?: number; + trustScore?: number; + benchmarkScore?: number; + versions?: string[]; + source?: string; +} + +export interface SearchResponse { + error?: string; + results: SearchResult[]; + searchFilterApplied?: boolean; +} + +// Version state is still needed for validating search results +export type DocumentState = "initial" | "finalized" | "error" | "delete"; + +export type ContextRequest = { + query: string; + libraryId: string; +}; + +export type ContextResponse = { + data: string; +}; + +export interface ClientContext { + clientIp?: string; + apiKey?: string; + clientInfo?: { + ide?: string; + version?: string; + }; + transport?: "stdio" | "http"; + sessionId?: string; + /** Mutable: set by the upstream API layer when the backend signals the + * client should be prompted to sign in. Read by the auth-prompt wrapper. */ + shouldPrompt?: boolean; +} diff --git a/packages/mcp/src/lib/utils.ts b/packages/mcp/src/lib/utils.ts new file mode 100644 index 0000000..6016425 --- /dev/null +++ b/packages/mcp/src/lib/utils.ts @@ -0,0 +1,98 @@ +import { SearchResponse, SearchResult } from "./types.js"; + +/** + * Maps numeric source reputation score to an interpretable label for LLM consumption. + * + * @returns One of: "High", "Medium", "Low", or "Unknown" + */ +function getSourceReputationLabel( + sourceReputation?: number +): "High" | "Medium" | "Low" | "Unknown" { + if (sourceReputation === undefined || sourceReputation < 0) return "Unknown"; + if (sourceReputation >= 7) return "High"; + if (sourceReputation >= 4) return "Medium"; + return "Low"; +} + +/** + * Formats a search result into a human-readable string representation. + * Only shows code snippet count and GitHub stars when available (not equal to -1). + * + * @param result The SearchResult object to format + * @returns A formatted string with library information + */ +export function formatSearchResult(result: SearchResult): string { + // Always include these basic details + const formattedResult = [ + `- Title: ${result.title}`, + `- Context7-compatible library ID: ${result.id}`, + `- Description: ${result.description}`, + ]; + + // Only add code snippets count if it's a valid value + if (result.totalSnippets !== -1 && result.totalSnippets !== undefined) { + formattedResult.push(`- Code Snippets: ${result.totalSnippets}`); + } + + // Always add categorized source reputation + const reputationLabel = getSourceReputationLabel(result.trustScore); + formattedResult.push(`- Source Reputation: ${reputationLabel}`); + + // Only add benchmark score if it's a valid value + if (result.benchmarkScore !== undefined && result.benchmarkScore > 0) { + formattedResult.push(`- Benchmark Score: ${result.benchmarkScore}`); + } + + // Only add versions if it's a valid value + if (result.versions !== undefined && result.versions.length > 0) { + formattedResult.push(`- Versions: ${result.versions.join(", ")}`); + } + + if (result.source) { + formattedResult.push(`- Source: ${result.source}`); + } + + // Join all parts with newlines + return formattedResult.join("\n"); +} + +/** + * Formats a search response into a human-readable string representation. + * Each result is formatted using formatSearchResult. + * + * @param searchResponse The SearchResponse object to format + * @returns A formatted string with search results + */ +export function formatSearchResults(searchResponse: SearchResponse): string { + if (!searchResponse.results || searchResponse.results.length === 0) { + return "No documentation libraries found matching your query."; + } + + const parts: string[] = []; + + if (searchResponse.searchFilterApplied) { + parts.push( + "**Note:** Your results only include libraries matching your teamspace's library filters. To adjust quality thresholds or blocked libraries, update your filters at https://context7.com/dashboard?tab=policies" + ); + } + + const formattedResults = searchResponse.results.map(formatSearchResult); + parts.push(formattedResults.join("\n----------\n")); + + return parts.join("\n\n"); +} + +/** + * Extract client info from User-Agent header. + * Parses formats like "Cursor/2.2.44 (darwin arm64)" or "claude-code/2.0.71" + */ +export function extractClientInfoFromUserAgent( + userAgent: string | undefined +): { ide?: string; version?: string } | undefined { + if (!userAgent) return undefined; + const match = userAgent.match(/^([^\/\s]+)\/([^\s(]+)/); + if (match) { + return { ide: match[1], version: match[2] }; + } + return undefined; +} diff --git a/packages/mcp/test/certificate.test.ts b/packages/mcp/test/certificate.test.ts new file mode 100644 index 0000000..3fad3b7 --- /dev/null +++ b/packages/mcp/test/certificate.test.ts @@ -0,0 +1,41 @@ +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { expect, test } from "vitest"; + +import { getDefaultCACertificates, loadCustomCACerts } from "../src/lib/api.js"; + +test("loadCustomCACerts returns undefined when no path is provided", () => { + expect(loadCustomCACerts(undefined)).toBeUndefined(); +}); + +test("loadCustomCACerts appends custom certs to Node default CAs", () => { + const tempDir = mkdtempSync(join(tmpdir(), "context7-ca-test-")); + const certPath = join(tempDir, "custom-ca.pem"); + const customCert = [ + "-----BEGIN CERTIFICATE-----", + "MIIBhTCCASugAwIBAgIUPcY2K4+testonlycertificateblockA9xYwCgYIKoZIzj0E", + "AwIwGDEWMBQGA1UEAwwNQ29udGV4dDcgVGVzdDAeFw0yNjA0MTAwMDAwMDBaFw0y", + "NjA0MTEwMDAwMDBaMBgxFjAUBgNVBAMMDUNvbnRleHQ3IFRlc3QwWTATBgcqhkjO", + "PQIBBggqhkjOPQMBBwNCAASrK8V0k5YJmN5v1J3t2G9u8rY3C2Jw4P3u8K1JdQxWl", + "m0x1X4Q2aO2m1QvX7p8oI1Y7r9cT5n6s4a8t0pVx4XWPo1MwUTAdBgNVHQ4EFgQU", + "B1a8wN1Yv3e6m7J4k2a9jX0wCgYIKoZIzj0EAwIDSAAwRQIhALyM2n0XWw8b0e9j", + "i0X9l3fY8o0s5Q0d3sV9mH0K7v5aAiB5a1T3qK9zR6wP8sV3mT7aN2k4dP6qC8e1", + "n0uWJ0x4Qg==", + "-----END CERTIFICATE-----", + ].join("\n"); + + writeFileSync(certPath, `${customCert}\n`, "utf-8"); + + try { + const defaultCAs = getDefaultCACertificates(); + const mergedCAs = loadCustomCACerts(certPath); + + expect(mergedCAs).toBeDefined(); + expect(mergedCAs).toHaveLength(defaultCAs.length + 1); + expect(mergedCAs?.slice(0, defaultCAs.length)).toEqual(defaultCAs); + expect(mergedCAs?.at(-1)).toBe(`${customCert}\n`); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/packages/mcp/test/client-ip.test.ts b/packages/mcp/test/client-ip.test.ts new file mode 100644 index 0000000..6b41529 --- /dev/null +++ b/packages/mcp/test/client-ip.test.ts @@ -0,0 +1,96 @@ +import { describe, expect, test } from "vitest"; +import type express from "express"; +import { getClientIp, isPrivateOrLocalIp } from "../src/lib/client-ip.js"; + +describe("isPrivateOrLocalIp", () => { + test.each([ + "10.0.0.1", + "192.168.1.1", + "172.16.0.1", + "127.0.0.1", + "169.254.1.1", + "100.64.0.1", + "100.127.255.255", + "::1", + "0::1", + "0:0:0:0:0:0:0:1", + "fe80::1", + "FE80::1", + "febf::1", + "fc00::1", + "fd12::1", + "fdff::1", + "::ffff:127.0.0.1", + ])("treats %s as private or local", (ip) => { + expect(isPrivateOrLocalIp(ip)).toBe(true); + }); + + test.each([ + "8.8.8.8", + "203.0.113.10", + "100.63.255.255", + "100.128.0.1", + "2001:db8::1", + "1::1", + "::11", + "::ffff:8.8.8.8", + // abbreviated first hextets that look like fe80::/10 or fc00::/7 but are not + "fe8::1", + "fc::1", + "fd0::1", + // fec0::/10 (deprecated site-local) is outside fe80::/10 + "fec0::1", + ])("treats %s as public", (ip) => { + expect(isPrivateOrLocalIp(ip)).toBe(false); + }); +}); + +describe("getClientIp", () => { + function makeRequest(headers: Record): express.Request { + return { + headers, + socket: undefined, + } as express.Request; + } + + test("skips loopback and link-local entries in X-Forwarded-For", () => { + const req = makeRequest({ + "x-forwarded-for": "127.0.0.1, 8.8.8.8", + }); + + expect(getClientIp(req)).toBe("8.8.8.8"); + }); + + test("skips RFC1918 and returns the first public forwarded IP", () => { + const req = makeRequest({ + "x-forwarded-for": "10.0.0.1, 192.168.0.2, 203.0.113.10", + }); + + expect(getClientIp(req)).toBe("203.0.113.10"); + }); + + test("skips IPv6 loopback and private ranges in X-Forwarded-For", () => { + const req = makeRequest({ + "x-forwarded-for": "::1, fe80::1, fc00::1, 2001:db8::5", + }); + + expect(getClientIp(req)).toBe("2001:db8::5"); + }); + + test("falls back to the first forwarded IP when all entries are private", () => { + const req = makeRequest({ + "x-forwarded-for": "127.0.0.1, 10.0.0.1", + }); + + expect(getClientIp(req)).toBe("127.0.0.1"); + }); + + test("uses socket remote address when X-Forwarded-For is absent", () => { + const req = { + headers: {}, + socket: { remoteAddress: "::ffff:203.0.113.10" }, + } as express.Request; + + expect(getClientIp(req)).toBe("203.0.113.10"); + }); +}); diff --git a/packages/mcp/test/jwt.test.ts b/packages/mcp/test/jwt.test.ts new file mode 100644 index 0000000..4abd8cc --- /dev/null +++ b/packages/mcp/test/jwt.test.ts @@ -0,0 +1,193 @@ +import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"; +import * as jose from "jose"; + +vi.mock("jose", async () => { + const actual = await vi.importActual("jose"); + return { + ...actual, + createRemoteJWKSet: vi.fn( + () => "fake-jwks" as unknown as ReturnType + ), + jwtVerify: vi.fn(), + }; +}); + +const TENANT_ID = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"; +const ENTRA_ISSUER = `https://login.microsoftonline.com/${TENANT_ID}/v2.0`; +const AUDIENCE = "6ff6a635-03d9-472d-a7f1-dc98a4e5fde2"; + +async function loadModule() { + vi.resetModules(); + return import("../src/lib/jwt.js"); +} + +function makeFetchResponse(init: Partial & { jsonData?: unknown }): Response { + const { jsonData, ...rest } = init; + return { + ok: true, + status: 200, + json: async () => jsonData, + ...rest, + } as Response; +} + +function makeEntraToken(payload: jose.JWTPayload): string { + const header = Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })).toString("base64url"); + const body = Buffer.from(JSON.stringify(payload)).toString("base64url"); + return `${header}.${body}.signature`; +} + +beforeEach(() => { + vi.stubGlobal("fetch", vi.fn()); +}); + +afterEach(() => { + vi.unstubAllGlobals(); + vi.clearAllMocks(); +}); + +describe("isJWT", () => { + test("returns true for 3-part dotted strings", async () => { + const { isJWT } = await loadModule(); + expect(isJWT("a.b.c")).toBe(true); + }); + + test("returns false for non-JWT strings", async () => { + const { isJWT } = await loadModule(); + expect(isJWT("not-a-jwt")).toBe(false); + expect(isJWT("only.two")).toBe(false); + expect(isJWT("a.b.c.d")).toBe(false); + }); +}); + +describe("validateJWT - Entra path", () => { + test("validates token after fetching tenant config", async () => { + const fetchMock = vi.mocked(fetch); + fetchMock.mockResolvedValueOnce( + makeFetchResponse({ + jsonData: { teamspaceId: "team-1", tenantId: TENANT_ID, requiredScope: "mcp.access" }, + }) + ); + vi.mocked(jose.jwtVerify).mockResolvedValue({ + payload: { oid: "user-oid", scp: "mcp.access" }, + protectedHeader: { alg: "RS256" }, + } as unknown as Awaited>); + + const { validateJWT } = await loadModule(); + const result = await validateJWT(makeEntraToken({ iss: ENTRA_ISSUER, aud: AUDIENCE })); + + expect(result.valid).toBe(true); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(fetchMock.mock.calls[0][0]).toContain(`/v2/entra/config/${AUDIENCE}`); + }); + + test("returns 'Unknown audience' when config endpoint returns 404", async () => { + vi.mocked(fetch).mockResolvedValue(makeFetchResponse({ ok: false, status: 404 })); + + const { validateJWT } = await loadModule(); + const result = await validateJWT(makeEntraToken({ iss: ENTRA_ISSUER, aud: "unknown-aud" })); + + expect(result.valid).toBe(false); + expect(result.error).toBe("Unknown audience"); + expect(jose.jwtVerify).not.toHaveBeenCalled(); + }); + + test("returns 'Missing required scope' when scp claim lacks the configured scope", async () => { + vi.mocked(fetch).mockResolvedValue( + makeFetchResponse({ + jsonData: { teamspaceId: "team-1", tenantId: TENANT_ID, requiredScope: "mcp.access" }, + }) + ); + vi.mocked(jose.jwtVerify).mockResolvedValue({ + payload: { scp: "other.scope" }, + protectedHeader: { alg: "RS256" }, + } as unknown as Awaited>); + + const { validateJWT } = await loadModule(); + const result = await validateJWT(makeEntraToken({ iss: ENTRA_ISSUER, aud: AUDIENCE })); + + expect(result.valid).toBe(false); + expect(result.error).toBe("Missing required scope"); + }); + + test("returns 'Missing audience' for Entra issuer with no aud claim", async () => { + const { validateJWT } = await loadModule(); + const result = await validateJWT(makeEntraToken({ iss: ENTRA_ISSUER })); + + expect(result.valid).toBe(false); + expect(result.error).toBe("Missing audience"); + expect(fetch).not.toHaveBeenCalled(); + }); + + test("caches config across repeated audiences", async () => { + const fetchMock = vi.mocked(fetch); + fetchMock.mockResolvedValue( + makeFetchResponse({ + jsonData: { teamspaceId: "team-1", tenantId: TENANT_ID, requiredScope: null }, + }) + ); + vi.mocked(jose.jwtVerify).mockResolvedValue({ + payload: { oid: "u" }, + protectedHeader: { alg: "RS256" }, + } as unknown as Awaited>); + + const { validateJWT } = await loadModule(); + const token = makeEntraToken({ iss: ENTRA_ISSUER, aud: AUDIENCE }); + await validateJWT(token); + await validateJWT(token); + + expect(fetchMock).toHaveBeenCalledTimes(1); + }); + + test("does not cache transient 500 errors — next request retries", async () => { + const fetchMock = vi.mocked(fetch); + fetchMock.mockResolvedValueOnce(makeFetchResponse({ ok: false, status: 500 })); + fetchMock.mockResolvedValueOnce( + makeFetchResponse({ + jsonData: { teamspaceId: "team-1", tenantId: TENANT_ID, requiredScope: null }, + }) + ); + vi.mocked(jose.jwtVerify).mockResolvedValue({ + payload: { oid: "u" }, + protectedHeader: { alg: "RS256" }, + } as unknown as Awaited>); + + const { validateJWT } = await loadModule(); + const token = makeEntraToken({ iss: ENTRA_ISSUER, aud: AUDIENCE }); + + const first = await validateJWT(token); + expect(first.valid).toBe(false); + expect(first.error).toBe("Unknown audience"); + + const second = await validateJWT(token); + expect(second.valid).toBe(true); + expect(fetchMock).toHaveBeenCalledTimes(2); + }); +}); + +describe("validateJWT - Clerk path", () => { + test("verifies against Clerk JWKS for non-Entra issuers", async () => { + vi.mocked(jose.jwtVerify).mockResolvedValue({ + payload: {}, + protectedHeader: { alg: "RS256" }, + } as unknown as Awaited>); + + const { validateJWT } = await loadModule(); + const result = await validateJWT(makeEntraToken({ iss: "https://clerk.context7.com" })); + + expect(result.valid).toBe(true); + expect(fetch).not.toHaveBeenCalled(); + }); + + test("returns 'Token expired' when jwtVerify throws JWTExpired", async () => { + vi.mocked(jose.jwtVerify).mockRejectedValue( + new jose.errors.JWTExpired("expired", { payload: {}, protectedHeader: { alg: "RS256" } }) + ); + + const { validateJWT } = await loadModule(); + const result = await validateJWT(makeEntraToken({ iss: "https://clerk.context7.com" })); + + expect(result.valid).toBe(false); + expect(result.error).toBe("Token expired"); + }); +}); diff --git a/packages/mcp/tsconfig.json b/packages/mcp/tsconfig.json new file mode 100644 index 0000000..83d8dcb --- /dev/null +++ b/packages/mcp/tsconfig.json @@ -0,0 +1,12 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "module": "NodeNext", + "moduleResolution": "NodeNext", + "resolveJsonModule": true, + "outDir": "./dist", + "rootDir": "./src" + }, + "include": ["src/**/*"], + "exclude": ["node_modules"] +} diff --git a/packages/mcp/tsconfig.test.json b/packages/mcp/tsconfig.test.json new file mode 100644 index 0000000..aa41654 --- /dev/null +++ b/packages/mcp/tsconfig.test.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "./dist-test", + "rootDir": "." + }, + "include": ["src/**/*", "test/**/*"], + "exclude": ["node_modules", "dist", "dist-test"] +} diff --git a/packages/pi/.prettierignore b/packages/pi/.prettierignore new file mode 100644 index 0000000..89a5b9f --- /dev/null +++ b/packages/pi/.prettierignore @@ -0,0 +1,9 @@ +# Dependencies +node_modules + +# Logs +*.log + +# Environment files +.env +.env.* diff --git a/packages/pi/CHANGELOG.md b/packages/pi/CHANGELOG.md new file mode 100644 index 0000000..f57bc6b --- /dev/null +++ b/packages/pi/CHANGELOG.md @@ -0,0 +1,13 @@ +# @upstash/context7-pi + +## 0.1.1 + +### Patch Changes + +- 33229cb: Clarify the `query-docs` query description so it asks for a single concept per query. When a question spans multiple distinct topics, callers are now told to make a separate query per concept instead of combining them (unless the question is about how the concepts interact), which avoids diluted, shallow results. Applied consistently across the MCP server, CLI, pi, and AI SDK tools. + +## 0.1.0 + +### Minor Changes + +- f91b40c: Initial release. Adds an official Context7 extension for the [pi coding agent](https://pi.dev) — registers `resolve-library-id` and `query-docs` tools, ships the `context7-docs` skill, and exposes a `/c7-docs` slash command. Wire format, error messages, and tool descriptions are copied verbatim from `@upstash/context7-mcp` so pi and MCP clients give the LLM identical instructions and output. Self-contained — no Context7 runtime dependencies. Works out of the box at IP-based rate limits; set `CONTEXT7_API_KEY` for the higher tier. Install with `pi install npm:@upstash/context7-pi`. diff --git a/packages/pi/LICENSE b/packages/pi/LICENSE new file mode 100644 index 0000000..0a1f72a --- /dev/null +++ b/packages/pi/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2021 Upstash, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/pi/README.md b/packages/pi/README.md new file mode 100644 index 0000000..1047476 --- /dev/null +++ b/packages/pi/README.md @@ -0,0 +1,46 @@ +# @upstash/context7-pi + +Official [Context7](https://context7.com) extension for the [pi coding agent](https://pi.dev). + +Adds up-to-date library documentation to pi via two LLM-callable tools — `resolve-library-id` and `query-docs` — plus a skill that teaches the agent when to use them and a `/c7-docs` slash command for manual lookups. + +## Install + +```bash +pi install npm:@upstash/context7-pi +``` + +## Authenticate + +The extension works without any setup at IP-based rate limits — useful for trying it out. For higher quotas, generate a free key at [context7.com/dashboard](https://context7.com/dashboard) and export it: + +```bash +export CONTEXT7_API_KEY=ctx7sk_... +``` + +Set it in your shell profile so pi picks it up on launch. + +## What it adds + +- **`resolve-library-id`** — converts a package or product name to a Context7 library ID (e.g. `Next.js` → `/vercel/next.js`). The agent should call this first. +- **`query-docs`** — fetches documentation and code examples for a resolved library ID. +- **`context7-docs` skill** — instructs the agent to reach for these tools whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service. +- **`/c7-docs `** — slash command that runs the resolve + query flow in one shot. + +## Usage + +Once installed, just ask the agent a docs question and the tools are invoked automatically: + +``` +how do I configure caching in Next.js 16? +``` + +For a manual lookup: + +``` +/c7-docs next.js Cache Components +``` + +## License + +MIT diff --git a/packages/pi/__tests__/extension.test.ts b/packages/pi/__tests__/extension.test.ts new file mode 100644 index 0000000..bd0b54d --- /dev/null +++ b/packages/pi/__tests__/extension.test.ts @@ -0,0 +1,56 @@ +import { describe, it, expect } from "vitest"; +import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent"; +import extension from "../extensions/context7"; + +function collectTools(): Map { + const tools = new Map(); + const pi = { + registerTool(def: ToolDefinition) { + tools.set(def.name, def); + }, + } as unknown as ExtensionAPI; + extension(pi); + return tools; +} + +describe("extension registration", () => { + const tools = collectTools(); + + it("registers resolve-library-id and query-docs", () => { + expect([...tools.keys()].sort()).toEqual(["query-docs", "resolve-library-id"]); + }); + + function paramKeys(def: ToolDefinition): string[] { + const schema = def.parameters as { properties: Record }; + return Object.keys(schema.properties).sort(); + } + + it("resolve-library-id has query + libraryName params", () => { + const def = tools.get("resolve-library-id")!; + expect(paramKeys(def)).toEqual(["libraryName", "query"]); + expect(def.description).toContain("Context7"); + }); + + it("query-docs has libraryId + query params", () => { + const def = tools.get("query-docs")!; + expect(paramKeys(def)).toEqual(["libraryId", "query"]); + expect(def.description).toContain("Context7"); + }); +}); + +describe("live Context7 API", () => { + const tools = collectTools(); + + it("resolve-library-id returns text for a real library", async () => { + const def = tools.get("resolve-library-id")!; + const result = await def.execute( + "test-call", + { query: "how do hooks work?", libraryName: "React" }, + undefined, + undefined, + {} as never + ); + expect(result.content[0].type).toBe("text"); + expect((result.content[0] as { text: string }).text).toMatch(/react/i); + }); +}); diff --git a/packages/pi/eslint.config.js b/packages/pi/eslint.config.js new file mode 100644 index 0000000..703cdb2 --- /dev/null +++ b/packages/pi/eslint.config.js @@ -0,0 +1,41 @@ +import { defineConfig } from "eslint/config"; +import tseslint from "typescript-eslint"; +import eslintPluginPrettier from "eslint-plugin-prettier"; + +export default defineConfig( + { + ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"], + }, + { + files: ["**/*.ts", "**/*.tsx"], + languageOptions: { + ecmaVersion: 2020, + sourceType: "module", + parser: tseslint.parser, + parserOptions: { + project: "./tsconfig.json", + tsconfigRootDir: import.meta.dirname, + }, + globals: { + process: "readonly", + require: "readonly", + module: "writable", + console: "readonly", + }, + }, + linterOptions: { + reportUnusedDisableDirectives: true, + }, + plugins: { + "@typescript-eslint": tseslint.plugin, + prettier: eslintPluginPrettier, + }, + rules: { + ...tseslint.configs.recommended.rules, + "@typescript-eslint/explicit-module-boundary-types": "off", + "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }], + "@typescript-eslint/no-explicit-any": "warn", + "prettier/prettier": "error", + }, + } +); diff --git a/packages/pi/extensions/context7.ts b/packages/pi/extensions/context7.ts new file mode 100644 index 0000000..ac16bf2 --- /dev/null +++ b/packages/pi/extensions/context7.ts @@ -0,0 +1,10 @@ +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; +import { resolveLibraryIdTool } from "../lib/tools/resolve-library-id"; +import { queryDocsTool } from "../lib/tools/query-docs"; + +function context7(pi: ExtensionAPI): void { + pi.registerTool(resolveLibraryIdTool); + pi.registerTool(queryDocsTool); +} + +export default context7; diff --git a/packages/pi/lib/api.ts b/packages/pi/lib/api.ts new file mode 100644 index 0000000..3dd351f --- /dev/null +++ b/packages/pi/lib/api.ts @@ -0,0 +1,65 @@ +// Adapted from @upstash/context7-mcp (packages/mcp/src/lib/api.ts) — kept +// minimal for pi: no proxy/CA-cert handling (pi controls the HTTP runtime), +// no per-request client context (pi passes through env). Keep wire format +// and error messages aligned with MCP. + +import type { SearchResponse } from "./types"; + +const BASE_URL = "https://context7.com/api"; + +function authHeaders(): Record { + const apiKey = process.env.CONTEXT7_API_KEY; + return apiKey ? { Authorization: `Bearer ${apiKey}` } : {}; +} + +async function parseErrorResponse(response: Response): Promise { + try { + const json = (await response.json()) as { message?: string }; + if (json.message) return json.message; + } catch { + // JSON parsing failed, fall through to status-based message + } + + const hasKey = Boolean(process.env.CONTEXT7_API_KEY); + if (response.status === 429) { + return hasKey + ? "Rate limited or quota exceeded. Upgrade your plan at https://context7.com/plans for higher limits." + : "Rate limited or quota exceeded. Create a free API key at https://context7.com/dashboard for higher limits."; + } + if (response.status === 404) { + return "The library you are trying to access does not exist. Please try with a different library ID."; + } + if (response.status === 401) { + return "Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix."; + } + return `Request failed with status ${response.status}. Please try again later.`; +} + +export async function searchLibraries(query: string, libraryName: string): Promise { + const url = new URL(`${BASE_URL}/v2/libs/search`); + url.searchParams.set("query", query); + url.searchParams.set("libraryName", libraryName); + + const response = await fetch(url, { headers: authHeaders() }); + if (!response.ok) { + return { results: [], error: await parseErrorResponse(response) }; + } + return (await response.json()) as SearchResponse; +} + +export async function fetchLibraryContext(query: string, libraryId: string): Promise { + const url = new URL(`${BASE_URL}/v2/context`); + url.searchParams.set("query", query); + url.searchParams.set("libraryId", libraryId); + + const response = await fetch(url, { headers: authHeaders() }); + if (!response.ok) { + return parseErrorResponse(response); + } + + const text = await response.text(); + if (!text) { + return "Documentation not found or not finalized for this library. This might have happened because you used an invalid Context7-compatible library ID. To get a valid Context7-compatible library ID, use the 'resolve-library-id' with the package name you wish to retrieve documentation for."; + } + return text; +} diff --git a/packages/pi/lib/format.ts b/packages/pi/lib/format.ts new file mode 100644 index 0000000..4427aa7 --- /dev/null +++ b/packages/pi/lib/format.ts @@ -0,0 +1,61 @@ +// Copied verbatim from @upstash/context7-mcp (packages/mcp/src/lib/utils.ts) +// to keep pi's text output identical to what MCP produces. Update both together. + +import type { SearchResponse, SearchResult } from "./types"; + +function getSourceReputationLabel( + sourceReputation?: number +): "High" | "Medium" | "Low" | "Unknown" { + if (sourceReputation === undefined || sourceReputation < 0) return "Unknown"; + if (sourceReputation >= 7) return "High"; + if (sourceReputation >= 4) return "Medium"; + return "Low"; +} + +export function formatSearchResult(result: SearchResult): string { + const formattedResult = [ + `- Title: ${result.title}`, + `- Context7-compatible library ID: ${result.id}`, + `- Description: ${result.description}`, + ]; + + if (result.totalSnippets !== -1 && result.totalSnippets !== undefined) { + formattedResult.push(`- Code Snippets: ${result.totalSnippets}`); + } + + const reputationLabel = getSourceReputationLabel(result.trustScore); + formattedResult.push(`- Source Reputation: ${reputationLabel}`); + + if (result.benchmarkScore !== undefined && result.benchmarkScore > 0) { + formattedResult.push(`- Benchmark Score: ${result.benchmarkScore}`); + } + + if (result.versions !== undefined && result.versions.length > 0) { + formattedResult.push(`- Versions: ${result.versions.join(", ")}`); + } + + if (result.source) { + formattedResult.push(`- Source: ${result.source}`); + } + + return formattedResult.join("\n"); +} + +export function formatSearchResults(searchResponse: SearchResponse): string { + if (!searchResponse.results || searchResponse.results.length === 0) { + return "No documentation libraries found matching your query."; + } + + const parts: string[] = []; + + if (searchResponse.searchFilterApplied) { + parts.push( + "**Note:** Your results only include libraries matching your teamspace's library filters. To adjust quality thresholds or blocked libraries, update your filters at https://context7.com/dashboard?tab=policies" + ); + } + + const formattedResults = searchResponse.results.map(formatSearchResult); + parts.push(formattedResults.join("\n----------\n")); + + return parts.join("\n\n"); +} diff --git a/packages/pi/lib/prompts.ts b/packages/pi/lib/prompts.ts new file mode 100644 index 0000000..a4d1ba3 --- /dev/null +++ b/packages/pi/lib/prompts.ts @@ -0,0 +1,60 @@ +// Tool titles, descriptions, and parameter descriptions are copied verbatim +// from @upstash/context7-mcp (packages/mcp/src/index.ts) so pi and MCP clients +// give the LLM identical instructions. Update both together when tweaking +// guidance. + +export const RESOLVE_LIBRARY_ID_TITLE = "Resolve Context7 Library ID"; + +export const RESOLVE_LIBRARY_ID_DESCRIPTION = `Resolves a package/product name to a Context7-compatible library ID and returns matching libraries. + +You MUST call this function before 'Query Documentation' tool to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. + +Each result includes: +- Library ID: Context7-compatible identifier (format: /org/project) +- Name: Library or package name +- Description: Short summary +- Code Snippets: Number of available code examples +- Source Reputation: Authority indicator (High, Medium, Low, or Unknown) +- Benchmark Score: Quality indicator (100 is the highest score) +- Versions: List of versions if available. Use one of those versions if the user provides a version in their query. The format of the version is /org/project/version. + +For best results, select libraries based on name match, source reputation, snippet coverage, benchmark score, and relevance to your use case. + +Selection Process: +1. Analyze the query to understand what library/package the user is looking for +2. Return the most relevant match based on: +- Name similarity to the query (exact matches prioritized) +- Description relevance to the query's intent +- Documentation coverage (prioritize libraries with higher Code Snippet counts) +- Source reputation (consider libraries with High or Medium reputation more authoritative) +- Benchmark Score: Quality indicator (100 is the highest score) + +Response Format: +- Return the selected library ID in a clearly marked section +- Provide a brief explanation for why this library was chosen +- If multiple good matches exist, acknowledge this but proceed with the most relevant one +- If no good matches exist, clearly state this and suggest query refinements + +For ambiguous queries, request clarification before proceeding with a best-guess match. + +IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.`; + +export const RESOLVE_LIBRARY_ID_QUERY_DESCRIPTION = + "The question or task you need help with. This is used to rank library results by relevance to what the user is trying to accomplish. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query."; + +export const RESOLVE_LIBRARY_ID_LIBRARY_NAME_DESCRIPTION = + "Library name to search for and retrieve a Context7-compatible library ID. Use the official library name with proper punctuation — e.g., 'Next.js' instead of 'nextjs', 'Customer.io' instead of 'customerio', 'Three.js' instead of 'threejs'."; + +export const QUERY_DOCS_TITLE = "Query Documentation"; + +export const QUERY_DOCS_DESCRIPTION = `Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework. + +You must call 'Resolve Context7 Library ID' tool first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. + +Do not call this tool more than 3 times per question.`; + +export const QUERY_DOCS_LIBRARY_ID_DESCRIPTION = + "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolve-library-id' or directly from user query in the format '/org/project' or '/org/project/version'."; + +export const QUERY_DOCS_QUERY_DESCRIPTION = + "The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query."; diff --git a/packages/pi/lib/result.ts b/packages/pi/lib/result.ts new file mode 100644 index 0000000..18ee1fa --- /dev/null +++ b/packages/pi/lib/result.ts @@ -0,0 +1,8 @@ +import type { AgentToolResult } from "@earendil-works/pi-coding-agent"; + +export function toToolResult(text: string): AgentToolResult { + return { + content: [{ type: "text", text }], + details: undefined, + }; +} diff --git a/packages/pi/lib/tools/query-docs.ts b/packages/pi/lib/tools/query-docs.ts new file mode 100644 index 0000000..28338f0 --- /dev/null +++ b/packages/pi/lib/tools/query-docs.ts @@ -0,0 +1,26 @@ +import { Type, type Static } from "typebox"; +import type { ToolDefinition } from "@earendil-works/pi-coding-agent"; +import { fetchLibraryContext } from "../api"; +import { toToolResult } from "../result"; +import { + QUERY_DOCS_TITLE, + QUERY_DOCS_DESCRIPTION, + QUERY_DOCS_LIBRARY_ID_DESCRIPTION, + QUERY_DOCS_QUERY_DESCRIPTION, +} from "../prompts"; + +const Params = Type.Object({ + libraryId: Type.String({ description: QUERY_DOCS_LIBRARY_ID_DESCRIPTION }), + query: Type.String({ description: QUERY_DOCS_QUERY_DESCRIPTION }), +}); + +export const queryDocsTool: ToolDefinition = { + name: "query-docs", + label: QUERY_DOCS_TITLE, + description: QUERY_DOCS_DESCRIPTION, + parameters: Params, + async execute(_toolCallId: string, params: Static) { + const text = await fetchLibraryContext(params.query, params.libraryId); + return toToolResult(text); + }, +}; diff --git a/packages/pi/lib/tools/resolve-library-id.ts b/packages/pi/lib/tools/resolve-library-id.ts new file mode 100644 index 0000000..637b37c --- /dev/null +++ b/packages/pi/lib/tools/resolve-library-id.ts @@ -0,0 +1,30 @@ +import { Type, type Static } from "typebox"; +import type { ToolDefinition } from "@earendil-works/pi-coding-agent"; +import { searchLibraries } from "../api"; +import { formatSearchResults } from "../format"; +import { toToolResult } from "../result"; +import { + RESOLVE_LIBRARY_ID_TITLE, + RESOLVE_LIBRARY_ID_DESCRIPTION, + RESOLVE_LIBRARY_ID_QUERY_DESCRIPTION, + RESOLVE_LIBRARY_ID_LIBRARY_NAME_DESCRIPTION, +} from "../prompts"; + +const Params = Type.Object({ + query: Type.String({ description: RESOLVE_LIBRARY_ID_QUERY_DESCRIPTION }), + libraryName: Type.String({ description: RESOLVE_LIBRARY_ID_LIBRARY_NAME_DESCRIPTION }), +}); + +export const resolveLibraryIdTool: ToolDefinition = { + name: "resolve-library-id", + label: RESOLVE_LIBRARY_ID_TITLE, + description: RESOLVE_LIBRARY_ID_DESCRIPTION, + parameters: Params, + async execute(_toolCallId: string, params: Static) { + const searchResponse = await searchLibraries(params.query, params.libraryName); + if (!searchResponse.results || searchResponse.results.length === 0) { + return toToolResult(searchResponse.error ?? "No libraries found matching the provided name."); + } + return toToolResult(`Available Libraries:\n\n${formatSearchResults(searchResponse)}`); + }, +}; diff --git a/packages/pi/lib/types.ts b/packages/pi/lib/types.ts new file mode 100644 index 0000000..ee75417 --- /dev/null +++ b/packages/pi/lib/types.ts @@ -0,0 +1,26 @@ +// Copied verbatim from @upstash/context7-mcp (packages/mcp/src/lib/types.ts) +// to keep pi's wire format in lockstep with MCP. Update both together. + +export interface SearchResult { + id: string; + title: string; + description: string; + branch: string; + lastUpdateDate: string; + state: DocumentState; + totalTokens: number; + totalSnippets: number; + stars?: number; + trustScore?: number; + benchmarkScore?: number; + versions?: string[]; + source?: string; +} + +export interface SearchResponse { + error?: string; + results: SearchResult[]; + searchFilterApplied?: boolean; +} + +export type DocumentState = "initial" | "finalized" | "error" | "delete"; diff --git a/packages/pi/package.json b/packages/pi/package.json new file mode 100644 index 0000000..91dae48 --- /dev/null +++ b/packages/pi/package.json @@ -0,0 +1,69 @@ +{ + "name": "@upstash/context7-pi", + "version": "0.1.1", + "description": "Official Context7 extension for pi.dev — adds resolve-library-id and query-docs tools to the pi coding agent", + "type": "module", + "pi": { + "extensions": [ + "./extensions" + ], + "skills": [ + "./skills" + ], + "prompts": [ + "./prompts" + ], + "image": "https://github.com/upstash/context7/blob/master/public/cover.png?raw=true" + }, + "files": [ + "extensions", + "lib", + "skills", + "prompts", + "LICENSE", + "README.md" + ], + "scripts": { + "test": "vitest run", + "test:watch": "vitest", + "typecheck": "tsc --noEmit", + "lint": "eslint .", + "lint:check": "eslint .", + "format": "prettier --write .", + "format:check": "prettier --check ." + }, + "peerDependencies": { + "@earendil-works/pi-coding-agent": "*", + "typebox": "*" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/upstash/context7.git", + "directory": "packages/pi" + }, + "keywords": [ + "pi-package", + "context7", + "documentation", + "upstash", + "ai", + "coding-agent" + ], + "author": "Upstash", + "license": "MIT", + "bugs": { + "url": "https://github.com/upstash/context7/issues" + }, + "homepage": "https://github.com/upstash/context7#readme", + "publishConfig": { + "access": "public" + }, + "devDependencies": { + "@earendil-works/pi-coding-agent": "^0.78.0", + "@types/node": "^25.9.1", + "dotenv": "^17.4.2", + "typebox": "^1.1.38", + "typescript": "^5.9.3", + "vitest": "^4.1.9" + } +} diff --git a/packages/pi/prompts/c7-docs.md b/packages/pi/prompts/c7-docs.md new file mode 100644 index 0000000..ba96e08 --- /dev/null +++ b/packages/pi/prompts/c7-docs.md @@ -0,0 +1,12 @@ +--- +description: Fetch Context7 documentation for a library +argument-hint: +--- + +Look up documentation for `$1` using Context7. + +1. Call the `resolve-library-id` tool with `libraryName="$1"` and `query="${@:2}"` to find the best matching library. +2. Call the `query-docs` tool with the selected library ID and `query="${@:2}"`. +3. Summarize the answer for the user with code examples from the returned snippets. Cite the Context7 library ID you used. + +If `$1` is already in `/org/project` or `/org/project/version` format, skip step 1 and call `query-docs` directly. diff --git a/packages/pi/skills/context7-docs/SKILL.md b/packages/pi/skills/context7-docs/SKILL.md new file mode 100644 index 0000000..1556e31 --- /dev/null +++ b/packages/pi/skills/context7-docs/SKILL.md @@ -0,0 +1,45 @@ +--- +name: context7-docs +description: >- + Fetch up-to-date documentation and code examples for any library, framework, + SDK, CLI tool, or cloud service. Use whenever the user asks about a specific + library — even well-known ones like React, Next.js, Prisma, Express, Tailwind, + Django, or Spring Boot — because training data may not reflect recent API + changes or version updates. + + Always use for: API syntax questions, configuration options, version migration + issues, "how do I" questions mentioning a library name, debugging that involves + library-specific behavior, setup instructions, and CLI tool usage. + + Use even when you think you know the answer. Do not rely on training data for + API details, signatures, or configuration options — they are frequently out of + date. Prefer this over web search for library documentation. +license: MIT +--- + +# Context7 Documentation Lookup + +Retrieve current documentation and code examples from [Context7](https://context7.com) using the `resolve-library-id` and `query-docs` tools that ship with this extension. + +## When to use + +Reach for these tools whenever a question involves a specific library, framework, SDK, CLI tool, or cloud service. Examples: + +- "How do I configure caching in Next.js 16?" +- "What's the syntax for Prisma's `findMany` with relations?" +- "Show me a working Tailwind v4 install for a Vite app." +- "How do I rate-limit with `@upstash/ratelimit`?" + +## Workflow + +1. **Resolve the library ID.** Call `resolve-library-id` with the library name and the user's question. The tool returns matching libraries with their Context7 IDs (`/org/project` format), descriptions, snippet counts, and quality scores. Pick the best match — prioritize official sources, name match, and high benchmark scores. +2. **Query the docs.** Call `query-docs` with the chosen library ID and the user's question, scoped to a single concept — if the question spans multiple distinct concepts, make a separate call per concept with the same library ID, unless the question is about how the concepts interact. The tool returns documentation snippets and code examples. +3. **Answer.** Cite the library ID you used and quote code examples verbatim when relevant. + +If the user supplies a library ID in `/org/project` or `/org/project/version` format directly, skip step 1 and call `query-docs` immediately. + +## Constraints + +- Do not call either tool more than 3 times per question. +- Do not pass API keys, passwords, credentials, personal data, or proprietary code as the `query` argument — it is sent to the Context7 API. +- Authentication uses the `CONTEXT7_API_KEY` environment variable. Get a key at https://context7.com/dashboard if requests fail with an auth error. diff --git a/packages/pi/tsconfig.json b/packages/pi/tsconfig.json new file mode 100644 index 0000000..3157803 --- /dev/null +++ b/packages/pi/tsconfig.json @@ -0,0 +1,24 @@ +{ + "compilerOptions": { + "lib": ["ESNext"], + "module": "esnext", + "target": "esnext", + "moduleResolution": "bundler", + "moduleDetection": "force", + "allowImportingTsExtensions": true, + "noEmit": true, + "strict": true, + "skipLibCheck": true, + "allowSyntheticDefaultImports": true, + "forceConsistentCasingInFileNames": true, + "allowJs": true + }, + "include": [ + "extensions/**/*", + "lib/**/*", + "__tests__/**/*", + "vitest.config.ts", + "eslint.config.js" + ], + "exclude": ["node_modules"] +} diff --git a/packages/pi/vitest.config.ts b/packages/pi/vitest.config.ts new file mode 100644 index 0000000..9f806ca --- /dev/null +++ b/packages/pi/vitest.config.ts @@ -0,0 +1,13 @@ +import { defineConfig } from "vitest/config"; +import path from "path"; +import { config } from "dotenv"; + +config({ path: path.resolve(__dirname, "../../.env") }); + +export default defineConfig({ + test: { + globals: true, + environment: "node", + include: ["__tests__/**/*.test.ts"], + }, +}); diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.md new file mode 100644 index 0000000..7e52b16 --- /dev/null +++ b/packages/sdk/CHANGELOG.md @@ -0,0 +1,34 @@ +# @upstash/context7-sdk + +## 0.3.1 + +### Patch Changes + +- f327589: Avoid throwing a raw `SyntaxError` when the server returns a non-JSON error body. `HttpClient.request()` now wraps the error-path `res.json()` in a `.catch`, so non-JSON responses (HTML 502s, plain-text 429s, Cloudflare challenge pages) fall back to `res.statusText` and always surface as a typed `Context7Error`. + +## 0.3.0 + +### Minor Changes + +- 9412e62: feat: Change SDK default response type from "txt" to "json" for both searchLibrary and getContext methods. AI SDK tools now explicitly use type: "txt" for LLM-friendly text responses. + +## 0.2.0 + +### Minor Changes + +- b3cd38a: feat: Simplify SDK API + - Replace `getDocs()` with `getContext(query, libraryId, options)` - now takes a query parameter for relevance-based retrieval + - Update `searchLibrary(query, libraryName)` to take both query and libraryName parameters + - Replace response types: `Library` and `Documentation` instead of `SearchResult`, `CodeDocsResponse`, `InfoDocsResponse`, etc. + - Remove pagination, mode, topic, and limit options from context retrieval + - Simplify `GetContextOptions` to only include `type: "json" | "txt"` + +## 0.1.0 + +### Minor Changes + +- 5e11d35: Initial release of the Context7 TypeScript SDK + - HTTP/REST client for the Context7 API + - `searchLibrary()` - Search for libraries in the Context7 database + - `getDocs()` - Retrieve documentation with filtering options + - Environment variable support for API key configuration diff --git a/packages/sdk/LICENSE b/packages/sdk/LICENSE new file mode 100644 index 0000000..17900de --- /dev/null +++ b/packages/sdk/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2021 Upstash, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/sdk/README.md b/packages/sdk/README.md new file mode 100644 index 0000000..292ed45 --- /dev/null +++ b/packages/sdk/README.md @@ -0,0 +1,94 @@ +# Upstash Context7 SDK + +> ⚠️ **Work in Progress**: This SDK is currently under active development. The API is subject to change and may introduce breaking changes in future releases. + +`@upstash/context7-sdk` is an HTTP/REST based client for TypeScript, built on top of the [Context7 API](https://context7.com). + +## Why Context7? + +LLMs rely on outdated or generic training data about the libraries you use. This leads to: + +- Code examples based on year-old training data +- Hallucinated APIs that don't exist +- Generic answers for old package versions + +Context7 solves this by providing up-to-date, version-specific documentation and code examples directly from the source. Use this SDK to: + +- Build AI agents with accurate, current documentation context +- Create RAG pipelines with reliable library documentation +- Power code generation tools with real API references + +## Quick Start + +### Install + +```bash +npm install @upstash/context7-sdk +``` + +### Get API Key + +Get your API key from [Context7](https://context7.com) + +## Basic Usage + +```ts +import { Context7 } from "@upstash/context7-sdk"; + +const client = new Context7({ + apiKey: "", +}); + +// Search for libraries +const libraries = await client.searchLibrary( + "I need to build a UI with components", + "react" +); +console.log(libraries[0].id); // "/facebook/react" + +// Get documentation as JSON array (default) +const docs = await client.getContext("How do I use hooks?", "/facebook/react"); +console.log(docs[0].title, docs[0].content); + +// Get documentation context as plain text +const context = await client.getContext( + "How do I use hooks?", + "/facebook/react", + { type: "txt" } +); +console.log(context); +``` + +## Configuration + +### Environment Variables + +You can set your API key via environment variable: + +```sh +CONTEXT7_API_KEY=ctx7sk-... +``` + +Then initialize without options: + +```ts +const client = new Context7(); +``` + +## Docs + +See the [documentation](https://context7.com/docs/sdks/ts/getting-started) for details. + +## Contributing + +### Running tests + +```sh +pnpm test +``` + +### Building + +```sh +pnpm build +``` diff --git a/packages/sdk/eslint.config.js b/packages/sdk/eslint.config.js new file mode 100644 index 0000000..aeb85ce --- /dev/null +++ b/packages/sdk/eslint.config.js @@ -0,0 +1,47 @@ +import { defineConfig } from "eslint/config"; +import tseslint from "typescript-eslint"; +import eslintPluginPrettier from "eslint-plugin-prettier"; + +export default defineConfig( + { + // Base ESLint configuration + ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"], + }, + { + files: ["**/*.ts", "**/*.tsx"], + languageOptions: { + ecmaVersion: 2020, + sourceType: "module", + parser: tseslint.parser, + parserOptions: { + project: "./tsconfig.json", + tsconfigRootDir: import.meta.dirname, + }, + globals: { + // Add Node.js globals + process: "readonly", + require: "readonly", + module: "writable", + console: "readonly", + }, + }, + // Settings for all files + linterOptions: { + reportUnusedDisableDirectives: true, + }, + plugins: { + "@typescript-eslint": tseslint.plugin, + prettier: eslintPluginPrettier, + }, + rules: { + // TypeScript recommended rules + ...tseslint.configs.recommended.rules, + // TypeScript rules + "@typescript-eslint/explicit-module-boundary-types": "off", + "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }], + "@typescript-eslint/no-explicit-any": "warn", + // Prettier integration + "prettier/prettier": "error", + }, + } +); diff --git a/packages/sdk/package.json b/packages/sdk/package.json new file mode 100644 index 0000000..5b6cdbd --- /dev/null +++ b/packages/sdk/package.json @@ -0,0 +1,56 @@ +{ + "name": "@upstash/context7-sdk", + "version": "0.3.1", + "description": "JavaScript/TypeScript SDK for Context7", + "scripts": { + "build": "tsup", + "test": "vitest run", + "test:watch": "vitest", + "typecheck": "tsc --noEmit", + "dev": "tsup --watch", + "clean": "rm -rf dist", + "lint": "eslint .", + "lint:check": "eslint ." + }, + "repository": { + "type": "git", + "url": "git+https://github.com/upstash/context7.git", + "directory": "packages/sdk" + }, + "keywords": [ + "context7", + "sdk", + "documentation", + "ai", + "upstash" + ], + "author": "Upstash", + "license": "MIT", + "type": "module", + "exports": { + ".": { + "import": "./dist/client.js", + "require": "./dist/client.cjs" + } + }, + "main": "./dist/client.cjs", + "module": "./dist/client.js", + "types": "./dist/client.d.ts", + "files": [ + "dist" + ], + "bugs": { + "url": "https://github.com/upstash/context7/issues" + }, + "homepage": "https://github.com/upstash/context7#readme", + "publishConfig": { + "access": "public" + }, + "devDependencies": { + "@types/node": "^25.0.3", + "dotenv": "^17.4.2", + "tsup": "^8.5.1", + "typescript": "^5.8.2", + "vitest": "^4.1.9" + } +} diff --git a/packages/sdk/prettier.config.mjs b/packages/sdk/prettier.config.mjs new file mode 100644 index 0000000..206e41e --- /dev/null +++ b/packages/sdk/prettier.config.mjs @@ -0,0 +1,13 @@ +/** + * @type {import('prettier').Config} + */ +const config = { + endOfLine: "lf", + singleQuote: false, + tabWidth: 2, + trailingComma: "es5", + printWidth: 100, + arrowParens: "always", +}; + +export default config; diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts new file mode 100644 index 0000000..d17ddfd --- /dev/null +++ b/packages/sdk/src/client.test.ts @@ -0,0 +1,179 @@ +import { describe, test, expect } from "vitest"; +import { Context7 } from "./client"; +import { Context7Error } from "@error"; + +describe("Context7 Client", () => { + const apiKey = process.env.CONTEXT7_API_KEY || process.env.API_KEY!; + + describe("constructor", () => { + test("should create client with API key", () => { + const client = new Context7({ apiKey }); + expect(client).toBeDefined(); + }); + + test("should create client from environment variables", () => { + const client = new Context7(); + expect(client).toBeDefined(); + }); + + test("should throw error when API key is missing", () => { + const originalEnv = process.env.CONTEXT7_API_KEY; + const originalApiKey = process.env.API_KEY; + + delete process.env.CONTEXT7_API_KEY; + delete process.env.API_KEY; + + expect(() => new Context7({ apiKey: "" })).toThrow(Context7Error); + expect(() => new Context7({})).toThrow(Context7Error); + expect(() => new Context7()).toThrow("API key is required"); + + if (originalEnv) process.env.CONTEXT7_API_KEY = originalEnv; + if (originalApiKey) process.env.API_KEY = originalApiKey; + }); + + test("should prefer config API key over environment variable", () => { + const customApiKey = "ctx7sk-custom-key"; + const client = new Context7({ apiKey: customApiKey }); + expect(client).toBeDefined(); + }); + }); + + describe("searchLibrary", () => { + const client = new Context7({ apiKey }); + + test("should search for libraries and return array directly", async () => { + const result = await client.searchLibrary("I need to build a UI", "react"); + + expect(result).toBeDefined(); + expect(Array.isArray(result)).toBe(true); + expect(result.length).toBeGreaterThan(0); + }); + + test("should return Library objects with all fields", async () => { + const result = await client.searchLibrary("I want to use TypeScript", "typescript"); + + expect(result.length).toBeGreaterThan(0); + const library = result[0]; + + expect(library).toHaveProperty("id"); + expect(library).toHaveProperty("name"); + expect(library).toHaveProperty("description"); + expect(library).toHaveProperty("totalSnippets"); + expect(library).toHaveProperty("trustScore"); + expect(library).toHaveProperty("benchmarkScore"); + }); + + test("should search with different queries", async () => { + const queries = ["vue", "express", "next"]; + + for (const query of queries) { + const result = await client.searchLibrary(`I want to use ${query}`, query); + expect(result.length).toBeGreaterThan(0); + } + }, 15000); + }); + + describe("getContext - JSON format (default)", () => { + const client = new Context7({ apiKey }); + + test("should get context as Documentation array (default)", async () => { + const result = await client.getContext("How to use hooks", "/react/react"); + + expect(result).toBeDefined(); + expect(Array.isArray(result)).toBe(true); + expect(result.length).toBeGreaterThan(0); + }); + + test("should get context with explicit json type", async () => { + const result = await client.getContext("How to use hooks", "/react/react", { + type: "json", + }); + + expect(result).toBeDefined(); + expect(Array.isArray(result)).toBe(true); + expect(result.length).toBeGreaterThan(0); + }); + + test("should have correct Documentation structure", async () => { + const result = await client.getContext("How to use hooks", "/react/react", { + type: "json", + }); + + expect(result.length).toBeGreaterThan(0); + const doc = result[0]; + expect(doc).toHaveProperty("title"); + expect(doc).toHaveProperty("content"); + expect(doc).toHaveProperty("source"); + expect(typeof doc.title).toBe("string"); + expect(typeof doc.content).toBe("string"); + expect(typeof doc.source).toBe("string"); + }); + }); + + describe("getContext - text format", () => { + const client = new Context7({ apiKey }); + + test("should get context as text string with type: txt", async () => { + const result = await client.getContext("How to use hooks", "/react/react", { + type: "txt", + }); + + expect(result).toBeDefined(); + expect(typeof result).toBe("string"); + expect(result.length).toBeGreaterThan(0); + }); + }); + + describe("getContext - different libraries", () => { + const client = new Context7({ apiKey }); + + test("should get context for Vue", async () => { + const result = await client.getContext("How to create components", "/vuejs/core"); + + expect(result).toBeDefined(); + expect(Array.isArray(result)).toBe(true); + expect(result.length).toBeGreaterThan(0); + }); + + test("should get context for Express", async () => { + const result = await client.getContext("How to create routes", "/expressjs/express"); + + expect(result).toBeDefined(); + expect(Array.isArray(result)).toBe(true); + expect(result.length).toBeGreaterThan(0); + }); + }); + + describe("error handling", () => { + const client = new Context7({ apiKey }); + + test("should handle invalid library ID gracefully", async () => { + await expect(client.getContext("test query", "/nonexistent/library")).rejects.toThrow(); + }); + + test("should handle invalid search query", async () => { + await expect(client.searchLibrary("", "")).rejects.toThrow(Context7Error); + }); + }); + + describe("type inference", () => { + const client = new Context7({ apiKey }); + + test("should infer Documentation[] for default (json) format", async () => { + const result = await client.getContext("How to use hooks", "/react/react"); + + expect(Array.isArray(result)).toBe(true); + expect(result[0]).toHaveProperty("title"); + expect(result[0]).toHaveProperty("content"); + expect(result[0]).toHaveProperty("source"); + }); + + test("should infer string type for txt format", async () => { + const result = await client.getContext("How to use hooks", "/react/react", { + type: "txt", + }); + + expect(typeof result).toBe("string"); + }); + }); +}); diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts new file mode 100644 index 0000000..e5c7665 --- /dev/null +++ b/packages/sdk/src/client.ts @@ -0,0 +1,132 @@ +import type { + Context7Config, + GetContextOptions, + SearchLibraryOptions, + Library, + Documentation, +} from "@commands/types"; +import { Context7Error } from "@error"; +import { HttpClient } from "@http"; +import { SearchLibraryCommand, GetContextCommand } from "@commands/index"; + +const DEFAULT_BASE_URL = "https://context7.com/api"; +const API_KEY_PREFIX = "ctx7sk"; + +export type * from "@commands/types"; +export * from "@error"; + +export class Context7 { + private httpClient: HttpClient; + + constructor(config: Context7Config = {}) { + const apiKey = config.apiKey || process.env.CONTEXT7_API_KEY; + + if (!apiKey) { + throw new Context7Error( + "API key is required. Pass it in the config or set CONTEXT7_API_KEY environment variable." + ); + } + + if (!apiKey.startsWith(API_KEY_PREFIX)) { + console.warn(`API key should start with '${API_KEY_PREFIX}'`); + } + + this.httpClient = new HttpClient({ + baseUrl: DEFAULT_BASE_URL, + headers: { + Authorization: `Bearer ${apiKey}`, + }, + retry: { + retries: 5, + backoff: (retryCount) => Math.exp(retryCount) * 50, + }, + cache: "no-store", + }); + } + + /** + * Search for libraries matching the given query as JSON (array of Library objects) + */ + async searchLibrary( + query: string, + libraryName: string, + options: SearchLibraryOptions & { type: "json" } + ): Promise; + + /** + * Search for libraries matching the given query as plain text + */ + async searchLibrary( + query: string, + libraryName: string, + options: SearchLibraryOptions & { type: "txt" } + ): Promise; + + /** + * Search for libraries matching the given query (defaults to JSON) + */ + async searchLibrary( + query: string, + libraryName: string, + options?: SearchLibraryOptions + ): Promise; + + /** + * Search for libraries matching the given query + * @param query The user's question or task (used for relevance ranking) + * @param libraryName The library name to search for + * @param options Response format options + * @returns Array of matching libraries (json) or formatted text (txt) + */ + async searchLibrary( + query: string, + libraryName: string, + options?: SearchLibraryOptions + ): Promise { + const command = new SearchLibraryCommand(query, libraryName, options); + return await command.exec(this.httpClient); + } + + /** + * Get documentation context for a library as JSON (array of documentation snippets) + */ + async getContext( + query: string, + libraryId: string, + options: GetContextOptions & { type: "json" } + ): Promise; + + /** + * Get documentation context for a library as plain text + */ + async getContext( + query: string, + libraryId: string, + options: GetContextOptions & { type: "txt" } + ): Promise; + + /** + * Get documentation context for a library (defaults to JSON) + */ + async getContext( + query: string, + libraryId: string, + options?: GetContextOptions + ): Promise; + + /** + * Get documentation context for a library + * @param query The user's question or task + * @param libraryId Context7 library ID (e.g., "/react/react") + * @param options Response format options + * @returns Documentation as Documentation[] (json, default) or string (txt) + */ + async getContext( + query: string, + libraryId: string, + options?: GetContextOptions + ): Promise { + const command = new GetContextCommand(query, libraryId, options); + return await command.exec(this.httpClient); + } +} diff --git a/packages/sdk/src/commands/command.ts b/packages/sdk/src/commands/command.ts new file mode 100644 index 0000000..bdbf628 --- /dev/null +++ b/packages/sdk/src/commands/command.ts @@ -0,0 +1,39 @@ +import type { Requester } from "@http"; + +export const _ENDPOINTS = ["v2/libs/search", "v2/context"]; + +export type EndpointVariants = (typeof _ENDPOINTS)[number]; + +export interface CommandRequest { + method?: "GET" | "POST"; + body?: unknown; + query?: Record; +} + +export class Command { + public readonly request: CommandRequest; + public readonly endpoint: EndpointVariants; + + constructor(request: CommandRequest, endpoint: EndpointVariants | string) { + this.request = request; + this.endpoint = endpoint; + } + + /** + * Execute the command using a client. + */ + public async exec(client: Requester): Promise { + const { result } = await client.request({ + method: this.request.method || "POST", + path: [this.endpoint], + query: this.request.query, + body: this.request.body, + }); + + if (result === undefined) { + throw new TypeError("Request did not return a result"); + } + + return result; + } +} diff --git a/packages/sdk/src/commands/get-context/index.test.ts b/packages/sdk/src/commands/get-context/index.test.ts new file mode 100644 index 0000000..ee5b0c6 --- /dev/null +++ b/packages/sdk/src/commands/get-context/index.test.ts @@ -0,0 +1,67 @@ +import { describe, test, expect } from "vitest"; +import { GetContextCommand } from "./index"; +import { newHttpClient } from "../../utils/test-utils"; +import { Context7 } from "../../client"; +import type { Documentation } from "@commands/types"; + +const httpClient = newHttpClient(); + +describe("GetContextCommand", () => { + test("should get library context as JSON (default)", async () => { + const command = new GetContextCommand("How to use hooks", "/react/react"); + const result = await command.exec(httpClient); + + expect(result).toBeDefined(); + expect(Array.isArray(result)).toBe(true); + + const docs = result as Documentation[]; + expect(docs.length).toBeGreaterThan(0); + + const doc = docs[0]; + expect(doc).toHaveProperty("title"); + expect(doc).toHaveProperty("content"); + expect(doc).toHaveProperty("source"); + }); + + test("should get library context as text with type: txt", async () => { + const command = new GetContextCommand("How to use hooks", "/react/react", { + type: "txt", + }); + const result = await command.exec(httpClient); + + expect(result).toBeDefined(); + expect(typeof result).toBe("string"); + expect((result as string).length).toBeGreaterThan(0); + }); + + test("should get library context as JSON using client (default)", async () => { + const client = new Context7({ + apiKey: process.env.CONTEXT7_API_KEY || process.env.API_KEY!, + }); + + const result = await client.getContext("How to use hooks", "/react/react"); + + expect(result).toBeDefined(); + expect(Array.isArray(result)).toBe(true); + expect(result.length).toBeGreaterThan(0); + + const doc = result[0]; + expect(doc).toHaveProperty("title"); + expect(doc).toHaveProperty("content"); + expect(doc).toHaveProperty("source"); + }); + + test("should get library context as text using client with type: txt", async () => { + const client = new Context7({ + apiKey: process.env.CONTEXT7_API_KEY || process.env.API_KEY!, + }); + + const result = await client.getContext("How to use hooks", "/react/react", { + type: "txt", + }); + + expect(result).toBeDefined(); + expect(typeof result).toBe("string"); + expect(result.length).toBeGreaterThan(0); + }); +}); diff --git a/packages/sdk/src/commands/get-context/index.ts b/packages/sdk/src/commands/get-context/index.ts new file mode 100644 index 0000000..9296328 --- /dev/null +++ b/packages/sdk/src/commands/get-context/index.ts @@ -0,0 +1,49 @@ +import { Command } from "@commands/command"; +import type { GetContextOptions, Documentation } from "@commands/types"; +import type { ApiContextJsonResponse } from "./types"; +import type { Requester } from "@http"; +import { Context7Error } from "@error"; +import { formatCodeSnippet, formatInfoSnippet } from "@utils/format"; + +const DEFAULT_TYPE = "json"; + +export class GetContextCommand extends Command { + private readonly responseType: "json" | "txt"; + + constructor(query: string, libraryId: string, options?: GetContextOptions) { + const queryParams: Record = {}; + + queryParams.query = query; + queryParams.libraryId = libraryId; + + const responseType = options?.type ?? DEFAULT_TYPE; + queryParams.type = responseType; + + super({ method: "GET", query: queryParams }, "v2/context"); + + this.responseType = responseType; + } + + public override async exec(client: Requester): Promise { + const { result } = await client.request({ + method: this.request.method || "GET", + path: [this.endpoint], + query: this.request.query, + body: this.request.body, + }); + + if (result === undefined) { + throw new Context7Error("Request did not return a result"); + } + + if (this.responseType === "txt" && typeof result === "string") { + return result; + } + + const apiResult = result as ApiContextJsonResponse; + const codeDocs = apiResult.codeSnippets.map(formatCodeSnippet); + const infoDocs = apiResult.infoSnippets.map(formatInfoSnippet); + + return [...codeDocs, ...infoDocs]; + } +} diff --git a/packages/sdk/src/commands/get-context/types.ts b/packages/sdk/src/commands/get-context/types.ts new file mode 100644 index 0000000..a55dae7 --- /dev/null +++ b/packages/sdk/src/commands/get-context/types.ts @@ -0,0 +1,21 @@ +export interface ApiCodeSnippet { + codeTitle: string; + codeDescription: string; + codeLanguage: string; + codeList: { language: string; code: string }[]; + codeId: string; + codeTokens?: number; + pageTitle?: string; +} + +export interface ApiInfoSnippet { + content: string; + breadcrumb?: string; + pageId: string; + contentTokens?: number; +} + +export interface ApiContextJsonResponse { + codeSnippets: ApiCodeSnippet[]; + infoSnippets: ApiInfoSnippet[]; +} diff --git a/packages/sdk/src/commands/index.ts b/packages/sdk/src/commands/index.ts new file mode 100644 index 0000000..0344413 --- /dev/null +++ b/packages/sdk/src/commands/index.ts @@ -0,0 +1,2 @@ +export * from "./get-context"; +export * from "./search-library"; diff --git a/packages/sdk/src/commands/search-library/index.test.ts b/packages/sdk/src/commands/search-library/index.test.ts new file mode 100644 index 0000000..f828298 --- /dev/null +++ b/packages/sdk/src/commands/search-library/index.test.ts @@ -0,0 +1,45 @@ +import { describe, test, expect } from "vitest"; +import { SearchLibraryCommand } from "./index"; +import { newHttpClient } from "../../utils/test-utils"; +import { Context7 } from "../../client"; + +const httpClient = newHttpClient(); + +describe("SearchLibraryCommand", () => { + test("should search for a library", async () => { + const command = new SearchLibraryCommand("I need to build a UI", "react"); + const result = await command.exec(httpClient); + + expect(result).toBeDefined(); + expect(Array.isArray(result)).toBe(true); + expect(result.length).toBeGreaterThan(0); + + const library = result[0]; + expect(library).toHaveProperty("id"); + expect(library).toHaveProperty("name"); + expect(library).toHaveProperty("description"); + expect(library).toHaveProperty("totalSnippets"); + expect(library).toHaveProperty("trustScore"); + expect(library).toHaveProperty("benchmarkScore"); + }); + + test("should search for a library using client", async () => { + const client = new Context7({ + apiKey: process.env.CONTEXT7_API_KEY || process.env.API_KEY!, + }); + + const result = await client.searchLibrary("I need to build a UI", "react"); + + expect(result).toBeDefined(); + expect(Array.isArray(result)).toBe(true); + expect(result.length).toBeGreaterThan(0); + + const library = result[0]; + expect(library).toHaveProperty("id"); + expect(library).toHaveProperty("name"); + expect(library).toHaveProperty("description"); + expect(library).toHaveProperty("totalSnippets"); + expect(library).toHaveProperty("trustScore"); + expect(library).toHaveProperty("benchmarkScore"); + }); +}); diff --git a/packages/sdk/src/commands/search-library/index.ts b/packages/sdk/src/commands/search-library/index.ts new file mode 100644 index 0000000..0bd5c00 --- /dev/null +++ b/packages/sdk/src/commands/search-library/index.ts @@ -0,0 +1,47 @@ +import { Command } from "@commands/command"; +import type { Library, SearchLibraryOptions } from "@commands/types"; +import type { ApiSearchResponse } from "./types"; +import type { Requester } from "@http"; +import { Context7Error } from "@error"; +import { formatLibrary, formatLibrariesAsText } from "@utils/format"; + +const DEFAULT_TYPE = "json"; + +export class SearchLibraryCommand extends Command { + private readonly responseType: "json" | "txt"; + + constructor(query: string, libraryName: string, options?: SearchLibraryOptions) { + if (!query || !libraryName) { + throw new Context7Error("query and libraryName are required"); + } + + const queryParams: Record = {}; + + queryParams.query = query; + queryParams.libraryName = libraryName; + + super({ method: "GET", query: queryParams }, "v2/libs/search"); + + this.responseType = options?.type ?? DEFAULT_TYPE; + } + + public override async exec(client: Requester): Promise { + const { result } = await client.request({ + method: this.request.method || "GET", + path: [this.endpoint], + query: this.request.query, + }); + + if (result === undefined) { + throw new Context7Error("Request did not return a result"); + } + + const libraries = result.results.map(formatLibrary); + + if (this.responseType === "txt") { + return formatLibrariesAsText(libraries); + } + + return libraries; + } +} diff --git a/packages/sdk/src/commands/search-library/types.ts b/packages/sdk/src/commands/search-library/types.ts new file mode 100644 index 0000000..e15635a --- /dev/null +++ b/packages/sdk/src/commands/search-library/types.ts @@ -0,0 +1,13 @@ +export interface ApiSearchResult { + id: string; + title: string; + description: string; + versions?: string[]; + totalSnippets?: number; + trustScore?: number; + benchmarkScore?: number; +} + +export interface ApiSearchResponse { + results: ApiSearchResult[]; +} diff --git a/packages/sdk/src/commands/types.ts b/packages/sdk/src/commands/types.ts new file mode 100644 index 0000000..607e3e2 --- /dev/null +++ b/packages/sdk/src/commands/types.ts @@ -0,0 +1,57 @@ +export interface Context7Config { + apiKey?: string; +} + +/** + * A library available in Context7 + */ +export interface Library { + /** Context7 library ID (e.g., "/react/react") */ + id: string; + /** Library display name */ + name: string; + /** Library description */ + description: string; + /** Number of documentation snippets available */ + totalSnippets: number; + /** Source reputation score (0-10) */ + trustScore: number; + /** Quality indicator score (0-100) */ + benchmarkScore: number; + /** Available versions/tags */ + versions?: string[]; +} + +/** + * A piece of documentation content + */ +export interface Documentation { + /** Title of the documentation snippet */ + title: string; + /** The documentation content (may include code blocks in markdown format) */ + content: string; + /** Source URL or identifier for the snippet */ + source: string; +} + +export interface GetContextOptions { + /** + * Response format. + * - "json": Returns Documentation[] array (default) + * - "txt": Returns formatted text string + * @default "json" + */ + type?: "json" | "txt"; +} + +export interface SearchLibraryOptions { + /** + * Response format. + * - "json": Returns Library[] array (default) + * - "txt": Returns formatted text string + * @default "json" + */ + type?: "json" | "txt"; +} + +export type QueryParams = Record; diff --git a/packages/sdk/src/error/index.ts b/packages/sdk/src/error/index.ts new file mode 100644 index 0000000..6b7b65a --- /dev/null +++ b/packages/sdk/src/error/index.ts @@ -0,0 +1,6 @@ +export class Context7Error extends Error { + constructor(message: string) { + super(message); + this.name = "Context7Error"; + } +} diff --git a/packages/sdk/src/http/index.test.ts b/packages/sdk/src/http/index.test.ts new file mode 100644 index 0000000..1d0d020 --- /dev/null +++ b/packages/sdk/src/http/index.test.ts @@ -0,0 +1,81 @@ +import { describe, test, expect, vi, afterEach } from "vitest"; +import { HttpClient } from "./index"; +import { Context7Error } from "@error"; + +function newClient(): HttpClient { + return new HttpClient({ + baseUrl: "https://example.com/api", + retry: false, + }); +} + +function mockFetch(response: Response) { + vi.stubGlobal( + "fetch", + vi.fn(() => Promise.resolve(response)) + ); +} + +describe("HttpClient error handling", () => { + afterEach(() => { + vi.unstubAllGlobals(); + }); + + test("throws Context7Error with message from JSON error body", async () => { + mockFetch( + new Response(JSON.stringify({ error: "rate limit exceeded" }), { + status: 429, + headers: { "content-type": "application/json" }, + }) + ); + + await expect(newClient().request({ path: ["search"] })).rejects.toThrowError( + new Context7Error("rate limit exceeded") + ); + }); + + test("falls back to message field when error field is absent", async () => { + mockFetch( + new Response(JSON.stringify({ message: "something went wrong" }), { + status: 400, + headers: { "content-type": "application/json" }, + }) + ); + + const error = await newClient() + .request({ path: ["search"] }) + .catch((e) => e); + + expect(error).toBeInstanceOf(Context7Error); + expect(error.message).toBe("something went wrong"); + }); + + test("throws Context7Error (not SyntaxError) on non-JSON error body", async () => { + mockFetch( + new Response("502 Bad Gateway", { + status: 502, + statusText: "Bad Gateway", + headers: { "content-type": "text/html" }, + }) + ); + + const error = await newClient() + .request({ path: ["search"] }) + .catch((e) => e); + + expect(error).toBeInstanceOf(Context7Error); + expect(error).not.toBeInstanceOf(SyntaxError); + expect(error.message).toBe("Bad Gateway"); + }); + + test("falls back to statusText on empty error body", async () => { + mockFetch(new Response("", { status: 503, statusText: "Service Unavailable" })); + + const error = await newClient() + .request({ path: ["search"] }) + .catch((e) => e); + + expect(error).toBeInstanceOf(Context7Error); + expect(error.message).toBe("Service Unavailable"); + }); +}); diff --git a/packages/sdk/src/http/index.ts b/packages/sdk/src/http/index.ts new file mode 100644 index 0000000..3f453ea --- /dev/null +++ b/packages/sdk/src/http/index.ts @@ -0,0 +1,212 @@ +import { Context7Error } from "@error"; + +type CacheSetting = + | "default" + | "force-cache" + | "no-cache" + | "no-store" + | "only-if-cached" + | "reload" + | false; + +export type Context7Request = { + path?: string[]; + /** + * Request body will be serialized to json + */ + body?: unknown; + /** + * HTTP method to use + * @default "POST" + */ + method?: "GET" | "POST"; + /** + * Query parameters for GET requests + */ + query?: Record; +}; +export type TxtResponseHeaders = { + page: number; + limit: number; + totalPages: number; + hasNext: boolean; + hasPrev: boolean; + totalTokens: number; +}; + +export type Context7Response = { + result?: TResult; + headers?: TxtResponseHeaders; +}; + +export type Requester = { + request: (req: Context7Request) => Promise>; +}; + +export type RetryConfig = + | false + | { + /** + * The number of retries to attempt before giving up. + * + * @default 5 + */ + retries?: number; + /** + * A backoff function receives the current retry count and returns a number in milliseconds to wait before retrying. + * + * @default + * ```ts + * Math.exp(retryCount) * 50 + * ``` + */ + backoff?: (retryCount: number) => number; + }; + +export type RequesterConfig = { + /** + * Configure the retry behaviour in case of network errors + */ + retry?: RetryConfig; + + /** + * Configure the cache behaviour + * @default "no-store" + */ + cache?: CacheSetting; +}; + +export type HttpClientConfig = { + headers?: Record; + baseUrl: string; + retry?: RetryConfig; + signal?: () => AbortSignal; +} & RequesterConfig; + +export class HttpClient implements Requester { + public baseUrl: string; + public headers: Record; + public readonly options: { + signal?: HttpClientConfig["signal"]; + cache?: CacheSetting; + }; + + public readonly retry: { + attempts: number; + backoff: (retryCount: number) => number; + }; + + public constructor(config: HttpClientConfig) { + this.options = { + cache: config.cache, + signal: config.signal, + }; + + this.baseUrl = config.baseUrl.replace(/\/$/, ""); + + this.headers = { + "Content-Type": "application/json", + ...config.headers, + }; + + this.retry = + typeof config?.retry === "boolean" && config?.retry === false + ? { + attempts: 1, + backoff: () => 0, + } + : { + attempts: config?.retry?.retries ?? 5, + backoff: config?.retry?.backoff ?? ((retryCount) => Math.exp(retryCount) * 50), + }; + } + + public async request(req: Context7Request): Promise> { + const method = req.method || "POST"; + + let url = [this.baseUrl, ...(req.path ?? [])].join("/"); + if (method === "GET" && req.query) { + const queryParams = new URLSearchParams(); + Object.entries(req.query).forEach(([key, value]) => { + if (value !== undefined) { + queryParams.append(key, String(value)); + } + }); + const queryString = queryParams.toString(); + if (queryString) { + url += `?${queryString}`; + } + } + + const requestOptions = { + cache: this.options.cache, + method, + headers: this.headers, + body: req.body ? JSON.stringify(req.body) : undefined, + keepalive: true, + signal: this.options.signal?.(), + }; + + let res: Response | null = null; + let error: Error | null = null; + + for (let i = 0; i <= this.retry.attempts; i++) { + try { + res = await fetch(url, requestOptions as RequestInit); + break; + } catch (error_) { + if (requestOptions.signal?.aborted) { + throw error_; + } + error = error_ as Error; + if (i < this.retry.attempts) { + await new Promise((r) => setTimeout(r, this.retry.backoff(i))); + } + } + } + if (!res) { + throw error ?? new Error("Exhausted all retries"); + } + + if (!res.ok) { + const errorBody = (await res.json().catch(() => ({}))) as { + error?: string; + message?: string; + }; + throw new Context7Error(errorBody.error || errorBody.message || res.statusText); + } + + const contentType = res.headers.get("content-type"); + + if (contentType?.includes("application/json")) { + const body = await res.json(); + return { result: body as TResult }; + } else { + const text = await res.text(); + const headers = this.extractTxtResponseHeaders(res.headers); + return { result: text as TResult, headers }; + } + } + + private extractTxtResponseHeaders(headers: Headers): TxtResponseHeaders | undefined { + const page = headers.get("x-context7-page"); + const limit = headers.get("x-context7-limit"); + const totalPages = headers.get("x-context7-total-pages"); + const hasNext = headers.get("x-context7-has-next"); + const hasPrev = headers.get("x-context7-has-prev"); + const totalTokens = headers.get("x-context7-total-tokens"); + + if (!page || !limit || !totalPages || !hasNext || !hasPrev || !totalTokens) { + return undefined; + } + + return { + page: parseInt(page, 10), + limit: parseInt(limit, 10), + totalPages: parseInt(totalPages, 10), + hasNext: hasNext === "true", + hasPrev: hasPrev === "true", + totalTokens: parseInt(totalTokens, 10), + }; + } +} diff --git a/packages/sdk/src/utils/format.ts b/packages/sdk/src/utils/format.ts new file mode 100644 index 0000000..5c40409 --- /dev/null +++ b/packages/sdk/src/utils/format.ts @@ -0,0 +1,94 @@ +import type { Documentation, Library } from "@commands/types"; +import type { ApiCodeSnippet, ApiInfoSnippet } from "@commands/get-context/types"; + +export function formatCodeSnippet(snippet: ApiCodeSnippet): Documentation { + const codeBlocks = snippet.codeList + .map((c) => `\`\`\`${c.language}\n${c.code}\n\`\`\``) + .join("\n\n"); + + const content = snippet.codeDescription + ? `${snippet.codeDescription}\n\n${codeBlocks}` + : codeBlocks; + + return { + title: snippet.codeTitle, + content, + source: snippet.codeId, + }; +} + +export function formatInfoSnippet(snippet: ApiInfoSnippet): Documentation { + return { + title: snippet.breadcrumb || "Documentation", + content: snippet.content, + source: snippet.pageId, + }; +} + +export function formatLibrary(r: { + id: string; + title: string; + description: string; + versions?: string[]; + totalSnippets?: number; + trustScore?: number; + benchmarkScore?: number; +}): Library { + return { + id: r.id, + name: r.title, + description: r.description, + totalSnippets: r.totalSnippets ?? 0, + trustScore: r.trustScore ?? 0, + benchmarkScore: r.benchmarkScore ?? 0, + versions: r.versions, + }; +} + +/** + * Maps numeric trust score to an interpretable label. + */ +function getTrustScoreLabel(trustScore?: number): "High" | "Medium" | "Low" | "Unknown" { + if (trustScore === undefined || trustScore < 0) return "Unknown"; + if (trustScore >= 7) return "High"; + if (trustScore >= 4) return "Medium"; + return "Low"; +} + +/** + * Formats a single library as a human-readable text block. + */ +export function formatLibraryAsText(library: Library): string { + const lines = [ + `- Title: ${library.name}`, + `- Context7-compatible library ID: ${library.id}`, + `- Description: ${library.description}`, + ]; + + if (library.totalSnippets > 0) { + lines.push(`- Code Snippets: ${library.totalSnippets}`); + } + + lines.push(`- Trust Score: ${getTrustScoreLabel(library.trustScore)}`); + + if (library.benchmarkScore > 0) { + lines.push(`- Benchmark Score: ${library.benchmarkScore}`); + } + + if (library.versions && library.versions.length > 0) { + lines.push(`- Versions: ${library.versions.join(", ")}`); + } + + return lines.join("\n"); +} + +/** + * Formats an array of libraries as human-readable text. + */ +export function formatLibrariesAsText(libraries: Library[]): string { + if (libraries.length === 0) { + return "No documentation libraries found matching your query."; + } + + return libraries.map(formatLibraryAsText).join("\n----------\n"); +} diff --git a/packages/sdk/src/utils/test-utils.ts b/packages/sdk/src/utils/test-utils.ts new file mode 100644 index 0000000..836941d --- /dev/null +++ b/packages/sdk/src/utils/test-utils.ts @@ -0,0 +1,21 @@ +import { HttpClient } from "@http"; + +export function newHttpClient(): HttpClient { + const apiKey = process.env.CONTEXT7_API_KEY || process.env.API_KEY; + + if (!apiKey) { + throw new Error("CONTEXT7_API_KEY or API_KEY environment variable is required for tests"); + } + + return new HttpClient({ + baseUrl: process.env.CONTEXT7_BASE_URL || "https://context7.com/api", + headers: { + Authorization: `Bearer ${apiKey}`, + }, + retry: { + retries: 3, + backoff: (retryCount) => Math.exp(retryCount) * 50, + }, + cache: "no-store", + }); +} diff --git a/packages/sdk/tsconfig.json b/packages/sdk/tsconfig.json new file mode 100644 index 0000000..3442062 --- /dev/null +++ b/packages/sdk/tsconfig.json @@ -0,0 +1,24 @@ +{ + "compilerOptions": { + "lib": ["ESNext"], + "module": "esnext", + "target": "esnext", + "moduleResolution": "bundler", + "moduleDetection": "force", + "allowImportingTsExtensions": true, + "noEmit": true, + "strict": true, + "skipLibCheck": true, + "allowSyntheticDefaultImports": true, + "forceConsistentCasingInFileNames": true, + "allowJs": true, + "paths": { + "@error": ["./src/error/index.ts"], + "@http": ["./src/http/index.ts"], + "@commands/*": ["./src/commands/*"], + "@utils/*": ["./src/utils/*"] + } + }, + "include": ["src/**/*", "tsup.config.ts", "vitest.config.ts", "eslint.config.js"], + "exclude": ["node_modules", "dist"] +} diff --git a/packages/sdk/tsup.config.ts b/packages/sdk/tsup.config.ts new file mode 100644 index 0000000..86c433e --- /dev/null +++ b/packages/sdk/tsup.config.ts @@ -0,0 +1,8 @@ +import { defineConfig } from "tsup"; + +export default defineConfig({ + entry: ["./src/client.ts"], + format: ["cjs", "esm"], + clean: true, + dts: true, +}); diff --git a/packages/sdk/vitest.config.ts b/packages/sdk/vitest.config.ts new file mode 100644 index 0000000..18a0a18 --- /dev/null +++ b/packages/sdk/vitest.config.ts @@ -0,0 +1,22 @@ +import { defineConfig } from "vitest/config"; +import path from "path"; +import dotenv from "dotenv"; + +dotenv.config({ path: path.resolve(__dirname, "../../.env") }); + +export default defineConfig({ + test: { + globals: true, + environment: "node", + include: ["src/**/*.test.ts"], + env: process.env, + }, + resolve: { + alias: { + "@commands": path.resolve(__dirname, "./src/commands"), + "@http": path.resolve(__dirname, "./src/http"), + "@error": path.resolve(__dirname, "./src/error/index.ts"), + "@utils": path.resolve(__dirname, "./src/utils"), + }, + }, +}); diff --git a/packages/tools-ai-sdk/CHANGELOG.md b/packages/tools-ai-sdk/CHANGELOG.md new file mode 100644 index 0000000..388d50c --- /dev/null +++ b/packages/tools-ai-sdk/CHANGELOG.md @@ -0,0 +1,54 @@ +# @upstash/context7-tools-ai-sdk + +## 0.2.4 + +### Patch Changes + +- 33229cb: Clarify the `query-docs` query description so it asks for a single concept per query. When a question spans multiple distinct topics, callers are now told to make a separate query per concept instead of combining them (unless the question is about how the concepts interact), which avoids diluted, shallow results. Applied consistently across the MCP server, CLI, pi, and AI SDK tools. + +## 0.2.3 + +### Patch Changes + +- 8322879: Improve resolve libryar id tool prompt to provide the libraryName query with proper format + +## 0.2.2 + +### Patch Changes + +- 02148ff: Bump zod from 3.x to 4.x + +## 0.2.1 + +### Patch Changes + +- 07a53dc: Upgrade ai peer dependency to >=6.0.0 for AI SDK v6 compatibility + +## 0.2.0 + +### Minor Changes + +- 9412e62: feat: Change SDK default response type from "txt" to "json" for both searchLibrary and getContext methods. AI SDK tools now explicitly use type: "txt" for LLM-friendly text responses. + +### Patch Changes + +- Updated dependencies [9412e62] + - @upstash/context7-sdk@0.3.0 + +## 0.1.0 + +### Minor Changes + +- b3cd38a: feat: Rename tools to match MCP naming conventions + - Rename `resolveLibrary` to `resolveLibraryId` with new `query` parameter + - Rename `getLibraryDocs` to `queryDocs` with new `query` parameter (replaces `topic`) + - Rename `RESOLVE_LIBRARY_DESCRIPTION` to `RESOLVE_LIBRARY_ID_DESCRIPTION` + - Rename `GET_LIBRARY_DOCS_DESCRIPTION` to `QUERY_DOCS_DESCRIPTION` + - Update type re-exports to match new SDK types (Library, Documentation, GetContextOptions) + - Remove deprecated `defaultMaxResults` option from Context7ToolsConfig and Context7AgentConfig + - Add rate limiting guidance to tool descriptions + +### Patch Changes + +- Updated dependencies [b3cd38a] + - @upstash/context7-sdk@0.2.0 diff --git a/packages/tools-ai-sdk/README.md b/packages/tools-ai-sdk/README.md new file mode 100644 index 0000000..6afb130 --- /dev/null +++ b/packages/tools-ai-sdk/README.md @@ -0,0 +1,101 @@ +# Upstash Context7 AI SDK + +`@upstash/context7-tools-ai-sdk` provides [Vercel AI SDK](https://ai-sdk.dev/) compatible tools and agents that give your AI applications access to up to date library documentation through Context7. + +Use this package to: + +- Add documentation lookup tools to your AI SDK workflows with `generateText` or `streamText` +- Create documentation aware agents using the pre-configured `Context7Agent` +- Build RAG pipelines that retrieve accurate, version specific code examples + +The package provides two main tools: + +- `resolveLibrary` - Searches Context7's database to find the correct library ID +- `getLibraryDocs` - Fetches documentation for a specific library with optional topic filtering + +## Quick Start + +### Install + +```bash +npm install @upstash/context7-tools-ai-sdk @upstash/context7-sdk ai zod +``` + +### Get API Key + +Get your API key from [Context7](https://context7.com) + +## Usage + +### Using Tools with `generateText` + +```typescript +import { resolveLibrary, getLibraryDocs } from "@upstash/context7-tools-ai-sdk"; +import { generateText, stepCountIs } from "ai"; +import { openai } from "@ai-sdk/openai"; + +const { text } = await generateText({ + model: openai("gpt-4o"), + prompt: "How do I use React Server Components?", + tools: { + resolveLibrary: resolveLibrary(), + getLibraryDocs: getLibraryDocs(), + }, + stopWhen: stepCountIs(5), +}); + +console.log(text); +``` + +### Using the Context7 Agent + +The package provides a pre-configured agent that handles the multi-step workflow automatically: + +```typescript +import { Context7Agent } from "@upstash/context7-tools-ai-sdk"; +import { anthropic } from "@ai-sdk/anthropic"; + +const agent = new Context7Agent({ + model: anthropic("claude-sonnet-4-20250514"), +}); + +const { text } = await agent.generate({ + prompt: "How do I set up routing in Next.js?", +}); + +console.log(text); +``` + +## Configuration + +### Environment Variables + +Set your API key via environment variable: + +```sh +CONTEXT7_API_KEY=ctx7sk-... +``` + +Then use tools and agents without explicit configuration: + +```typescript +const tool = resolveLibrary(); // Uses CONTEXT7_API_KEY automatically +``` + +## Docs + +See the [documentation](https://context7.com/docs/agentic-tools/ai-sdk/getting-started) for details. + +## Contributing + +### Running tests + +```sh +pnpm test +``` + +### Building + +```sh +pnpm build +``` diff --git a/packages/tools-ai-sdk/eslint.config.js b/packages/tools-ai-sdk/eslint.config.js new file mode 100644 index 0000000..aeb85ce --- /dev/null +++ b/packages/tools-ai-sdk/eslint.config.js @@ -0,0 +1,47 @@ +import { defineConfig } from "eslint/config"; +import tseslint from "typescript-eslint"; +import eslintPluginPrettier from "eslint-plugin-prettier"; + +export default defineConfig( + { + // Base ESLint configuration + ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"], + }, + { + files: ["**/*.ts", "**/*.tsx"], + languageOptions: { + ecmaVersion: 2020, + sourceType: "module", + parser: tseslint.parser, + parserOptions: { + project: "./tsconfig.json", + tsconfigRootDir: import.meta.dirname, + }, + globals: { + // Add Node.js globals + process: "readonly", + require: "readonly", + module: "writable", + console: "readonly", + }, + }, + // Settings for all files + linterOptions: { + reportUnusedDisableDirectives: true, + }, + plugins: { + "@typescript-eslint": tseslint.plugin, + prettier: eslintPluginPrettier, + }, + rules: { + // TypeScript recommended rules + ...tseslint.configs.recommended.rules, + // TypeScript rules + "@typescript-eslint/explicit-module-boundary-types": "off", + "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }], + "@typescript-eslint/no-explicit-any": "warn", + // Prettier integration + "prettier/prettier": "error", + }, + } +); diff --git a/packages/tools-ai-sdk/package.json b/packages/tools-ai-sdk/package.json new file mode 100644 index 0000000..125d62a --- /dev/null +++ b/packages/tools-ai-sdk/package.json @@ -0,0 +1,69 @@ +{ + "name": "@upstash/context7-tools-ai-sdk", + "version": "0.2.4", + "description": "Context7 tools for Vercel AI SDK", + "type": "module", + "main": "./dist/index.cjs", + "module": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js", + "require": "./dist/index.cjs" + }, + "./agent": { + "types": "./dist/agent.d.ts", + "import": "./dist/agent.js", + "require": "./dist/agent.cjs" + } + }, + "files": [ + "dist" + ], + "scripts": { + "build": "tsup", + "dev": "tsup --watch", + "test": "vitest run", + "typecheck": "tsc --noEmit", + "clean": "rm -rf dist" + }, + "peerDependencies": { + "@upstash/context7-sdk": ">=0.3.1", + "ai": ">=6.0.0", + "zod": ">=4.0.0" + }, + "devDependencies": { + "@upstash/context7-sdk": "workspace:*", + "ai": "^6.0.5", + "zod": "^4.4.3", + "@ai-sdk/amazon-bedrock": "^4.0.9", + "@types/node": "^25.0.3", + "dotenv": "^17.4.2", + "tsup": "^8.5.1", + "typescript": "^5.8.2", + "vitest": "^4.1.9" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/upstash/context7.git", + "directory": "packages/tools-ai-sdk" + }, + "keywords": [ + "context7", + "ai-sdk", + "vercel", + "documentation", + "agent", + "upstash" + ], + "author": "Upstash", + "license": "MIT", + "bugs": { + "url": "https://github.com/upstash/context7/issues" + }, + "homepage": "https://github.com/upstash/context7#readme", + "publishConfig": { + "access": "public" + } +} diff --git a/packages/tools-ai-sdk/src/agents/context7.ts b/packages/tools-ai-sdk/src/agents/context7.ts new file mode 100644 index 0000000..4957d83 --- /dev/null +++ b/packages/tools-ai-sdk/src/agents/context7.ts @@ -0,0 +1,64 @@ +import { ToolLoopAgent, type ToolLoopAgentSettings, type ToolSet, stepCountIs } from "ai"; +import { resolveLibraryId, queryDocs } from "@tools"; +import { AGENT_PROMPT } from "@prompts"; + +/** + * Configuration for Context7 agent. + */ +export interface Context7AgentConfig extends ToolLoopAgentSettings { + /** + * Context7 API key. If not provided, uses the CONTEXT7_API_KEY environment variable. + */ + apiKey?: string; +} + +/** + * Context7 documentation search agent + * + * The agent follows a multi-step workflow: + * 1. Resolves library names to Context7 library IDs + * 2. Fetches documentation for the resolved library + * 3. Provides answers with code examples + * + * @example + * ```typescript + * import { Context7Agent } from '@upstash/context7-tools-ai-sdk'; + * import { anthropic } from '@ai-sdk/anthropic'; + * + * const agent = new Context7Agent({ + * model: anthropic('claude-sonnet-4-20250514'), + * apiKey: 'your-context7-api-key', + * }); + * + * const result = await agent.generate({ + * prompt: 'How do I use React Server Components?', + * }); + * ``` + */ +export class Context7Agent extends ToolLoopAgent { + constructor(config: Context7AgentConfig) { + const { + model, + stopWhen = stepCountIs(5), + instructions, + apiKey, + + tools, + ...agentSettings + } = config; + + const context7Config = { apiKey }; + + super({ + ...agentSettings, + model, + instructions: instructions || AGENT_PROMPT, + tools: { + ...tools, + resolveLibraryId: resolveLibraryId(context7Config), + queryDocs: queryDocs(context7Config), + }, + stopWhen, + }); + } +} diff --git a/packages/tools-ai-sdk/src/agents/index.ts b/packages/tools-ai-sdk/src/agents/index.ts new file mode 100644 index 0000000..d803381 --- /dev/null +++ b/packages/tools-ai-sdk/src/agents/index.ts @@ -0,0 +1 @@ +export { Context7Agent, type Context7AgentConfig } from "./context7"; diff --git a/packages/tools-ai-sdk/src/index.test.ts b/packages/tools-ai-sdk/src/index.test.ts new file mode 100644 index 0000000..6302f54 --- /dev/null +++ b/packages/tools-ai-sdk/src/index.test.ts @@ -0,0 +1,228 @@ +import { describe, test, expect } from "vitest"; +import { generateText, stepCountIs, tool } from "ai"; +import { createAmazonBedrock } from "@ai-sdk/amazon-bedrock"; +import { z } from "zod"; +import { + resolveLibraryId, + queryDocs, + Context7Agent, + SYSTEM_PROMPT, + AGENT_PROMPT, + RESOLVE_LIBRARY_ID_DESCRIPTION, +} from "./index"; + +const bedrock = createAmazonBedrock({ + region: process.env.AWS_REGION, + apiKey: process.env.AWS_BEARER_TOKEN_BEDROCK, +}); + +describe("@upstash/context7-tools-ai-sdk", () => { + describe("Tool structure", () => { + test("resolveLibraryId() should return a tool object with correct structure", () => { + const tool = resolveLibraryId(); + + expect(tool).toBeDefined(); + expect(tool).toHaveProperty("execute"); + expect(tool).toHaveProperty("inputSchema"); + expect(tool).toHaveProperty("description"); + expect(tool.description).toContain("library"); + }); + + test("queryDocs() should return a tool object with correct structure", () => { + const tool = queryDocs(); + + expect(tool).toBeDefined(); + expect(tool).toHaveProperty("execute"); + expect(tool).toHaveProperty("inputSchema"); + expect(tool).toHaveProperty("description"); + expect(tool.description).toContain("documentation"); + }); + + test("tools should accept custom config", () => { + const resolveTool = resolveLibraryId({ + apiKey: "ctx7sk-test-key", + }); + + const docsTool = queryDocs({ + apiKey: "ctx7sk-test-key", + }); + + expect(resolveTool).toHaveProperty("execute"); + expect(docsTool).toHaveProperty("execute"); + }); + }); + + describe("Tool usage with generateText", () => { + test("resolveLibraryId tool should be called when searching for a library", async () => { + const result = await generateText({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + tools: { + resolveLibraryId: resolveLibraryId(), + }, + toolChoice: { type: "tool", toolName: "resolveLibraryId" }, + stopWhen: stepCountIs(2), + prompt: "Search for 'react' library", + }); + + expect(result.toolCalls.length).toBeGreaterThan(0); + expect(result.toolCalls[0].toolName).toBe("resolveLibraryId"); + expect(result.toolResults.length).toBeGreaterThan(0); + const toolResult = result.toolResults[0] as unknown as { output: string }; + expect(typeof toolResult.output).toBe("string"); + expect(toolResult.output).toContain("Context7-compatible library ID"); + }, 30000); + + test("queryDocs tool should fetch documentation", async () => { + const result = await generateText({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + tools: { + queryDocs: queryDocs(), + }, + toolChoice: { type: "tool", toolName: "queryDocs" }, + stopWhen: stepCountIs(2), + prompt: "Fetch documentation for library ID '/facebook/react' about hooks", + }); + + expect(result.toolCalls.length).toBeGreaterThan(0); + expect(result.toolCalls[0].toolName).toBe("queryDocs"); + expect(result.toolResults.length).toBeGreaterThan(0); + const toolResult = result.toolResults[0] as unknown as { output: string }; + expect(typeof toolResult.output).toBe("string"); + expect(toolResult.output.length).toBeGreaterThan(0); + }, 30000); + + test("both tools can work together in a multi-step flow", async () => { + const result = await generateText({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + tools: { + resolveLibraryId: resolveLibraryId(), + queryDocs: queryDocs(), + }, + stopWhen: stepCountIs(5), + prompt: + "First use resolveLibraryId to find the Next.js library, then use queryDocs to get documentation about routing", + }); + + const allToolCalls = result.steps.flatMap((step) => step.toolCalls); + const toolNames = allToolCalls.map((call) => call.toolName); + expect(toolNames).toContain("resolveLibraryId"); + expect(toolNames).toContain("queryDocs"); + }, 60000); + }); + + describe("Context7Agent class", () => { + test("should create an agent instance with model", () => { + const agent = new Context7Agent({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + }); + + expect(agent).toBeDefined(); + expect(agent).toHaveProperty("generate"); + expect(agent).toHaveProperty("stream"); + }); + + test("should accept custom stopWhen condition", () => { + const agent = new Context7Agent({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + stopWhen: stepCountIs(3), + }); + + expect(agent).toBeDefined(); + }); + + test("should accept custom instructions", () => { + const agent = new Context7Agent({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + instructions: "Custom instructions for testing", + }); + + expect(agent).toBeDefined(); + }); + + test("should accept Context7 config options", () => { + const agent = new Context7Agent({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + apiKey: "ctx7sk-test-key", + }); + + expect(agent).toBeDefined(); + }); + + test("should accept additional tools alongside Context7 tools", () => { + const customTool = tool({ + description: "A custom test tool", + inputSchema: z.object({ + input: z.string().describe("Test input"), + }), + execute: async ({ input }) => ({ result: `processed: ${input}` }), + }); + + const agent = new Context7Agent({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + tools: { + customTool, + }, + }); + + expect(agent).toBeDefined(); + }); + + test("should generate response using agent workflow", async () => { + const agent = new Context7Agent({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + stopWhen: stepCountIs(5), + }); + + const result = await agent.generate({ + prompt: "Find the React library and get documentation about hooks", + }); + + expect(result).toBeDefined(); + expect(result.steps.length).toBeGreaterThan(0); + + const allToolCalls = result.steps.flatMap((step) => step.toolCalls); + const toolNames = allToolCalls.map((call) => call.toolName); + expect(toolNames).toContain("resolveLibraryId"); + }, 60000); + + test("should include Context7 tools in generate result", async () => { + const agent = new Context7Agent({ + model: bedrock("anthropic.claude-3-haiku-20240307-v1:0"), + stopWhen: stepCountIs(5), + }); + + const result = await agent.generate({ + prompt: + "Use resolveLibraryId to search for Next.js, then use queryDocs to get routing documentation", + }); + + expect(result).toBeDefined(); + + const allToolCalls = result.steps.flatMap((step) => step.toolCalls); + const toolNames = allToolCalls.map((call) => call.toolName); + + expect(toolNames).toContain("resolveLibraryId"); + expect(toolNames).toContain("queryDocs"); + }, 60000); + }); + + describe("Prompt exports", () => { + test("should export SYSTEM_PROMPT", () => { + expect(SYSTEM_PROMPT).toBeDefined(); + expect(typeof SYSTEM_PROMPT).toBe("string"); + expect(SYSTEM_PROMPT.length).toBeGreaterThan(0); + }); + + test("should export AGENT_PROMPT", () => { + expect(AGENT_PROMPT).toBeDefined(); + expect(typeof AGENT_PROMPT).toBe("string"); + expect(AGENT_PROMPT).toContain("Context7"); + }); + + test("should export RESOLVE_LIBRARY_ID_DESCRIPTION", () => { + expect(RESOLVE_LIBRARY_ID_DESCRIPTION).toBeDefined(); + expect(typeof RESOLVE_LIBRARY_ID_DESCRIPTION).toBe("string"); + expect(RESOLVE_LIBRARY_ID_DESCRIPTION).toContain("library"); + }); + }); +}); diff --git a/packages/tools-ai-sdk/src/index.ts b/packages/tools-ai-sdk/src/index.ts new file mode 100644 index 0000000..5b224ec --- /dev/null +++ b/packages/tools-ai-sdk/src/index.ts @@ -0,0 +1,21 @@ +// Agents +export { Context7Agent, type Context7AgentConfig } from "@agents"; + +// Tools +export { resolveLibraryId, queryDocs, type Context7ToolsConfig } from "@tools"; + +// Prompts +export { + SYSTEM_PROMPT, + AGENT_PROMPT, + RESOLVE_LIBRARY_ID_DESCRIPTION, + QUERY_DOCS_DESCRIPTION, +} from "@prompts"; + +// Re-export useful types from SDK +export type { + Context7Config, + Library, + Documentation, + GetContextOptions, +} from "@upstash/context7-sdk"; diff --git a/packages/tools-ai-sdk/src/prompts/index.ts b/packages/tools-ai-sdk/src/prompts/index.ts new file mode 100644 index 0000000..1f12413 --- /dev/null +++ b/packages/tools-ai-sdk/src/prompts/index.ts @@ -0,0 +1,6 @@ +export { + SYSTEM_PROMPT, + AGENT_PROMPT, + RESOLVE_LIBRARY_ID_DESCRIPTION, + QUERY_DOCS_DESCRIPTION, +} from "./system"; diff --git a/packages/tools-ai-sdk/src/prompts/system.ts b/packages/tools-ai-sdk/src/prompts/system.ts new file mode 100644 index 0000000..bd0458c --- /dev/null +++ b/packages/tools-ai-sdk/src/prompts/system.ts @@ -0,0 +1,82 @@ +/** + * System prompts for Context7 AI SDK agents + */ + +/** + * Basic documentation assistant prompt + */ +export const SYSTEM_PROMPT = `You are a documentation search assistant powered by Context7. + +Your role is to help users find accurate, up-to-date documentation for libraries and frameworks. + +When answering questions: +1. Search for the relevant library documentation +2. Provide code examples when available +3. Cite your sources by mentioning the library ID used`; + +/** + * Detailed multi-step workflow prompt for comprehensive documentation retrieval + */ +export const AGENT_PROMPT = `You are a documentation search assistant powered by Context7. + +CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS: + +Step 1: ALWAYS start by calling 'resolveLibraryId' with the library name from the user's query + - Extract the main library/framework name (e.g., "React", "Next.js", "Vue") + - Call resolveLibraryId with just the library name + - Review ALL the search results returned + +Step 2: Analyze the results from resolveLibraryId and select the BEST library ID based on: + - Official sources (e.g., /reactjs/react.dev for React, /vercel/next.js for Next.js) + - Name similarity to what the user is looking for + - Description relevance + - Source reputation (High/Medium is better) + - Code snippet coverage (higher is better) + - Benchmark score (higher is better) + +Step 3: Call 'queryDocs' with the selected library ID and the user's query + - Use the exact library ID from the resolveLibraryId results + - Include the user's original question as the query parameter + +Step 4: Provide a clear answer with code examples from the documentation + +IMPORTANT: +- You MUST call resolveLibraryId first before calling queryDocs +- Do NOT skip resolveLibraryId - it helps you find the correct official documentation +- Do not call either tool more than 3 times per question +- Always cite which library ID you used`; + +/** + * Library resolution tool description + */ +export const RESOLVE_LIBRARY_ID_DESCRIPTION = `Resolves a package/product name to a Context7-compatible library ID and returns matching libraries. + +You MUST call this function before 'queryDocs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. + +Selection Process: +1. Analyze the query to understand what library/package the user is looking for +2. Return the most relevant match based on: +- Name similarity to the query (exact matches prioritized) +- Description relevance to the query's intent +- Documentation coverage (prioritize libraries with higher Code Snippet counts) +- Source reputation (consider libraries with High or Medium reputation more authoritative) +- Benchmark Score: Quality indicator (100 is the highest score) + +Response Format: +- Return the selected library ID in a clearly marked section +- Provide a brief explanation for why this library was chosen +- If multiple good matches exist, acknowledge this but proceed with the most relevant one +- If no good matches exist, clearly state this and suggest query refinements + +For ambiguous queries, request clarification before proceeding with a best-guess match. + +IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.`; + +/** + * Query docs tool description + */ +export const QUERY_DOCS_DESCRIPTION = `Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework. + +You must call 'resolveLibraryId' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query. + +IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.`; diff --git a/packages/tools-ai-sdk/src/tools/index.ts b/packages/tools-ai-sdk/src/tools/index.ts new file mode 100644 index 0000000..e9f1149 --- /dev/null +++ b/packages/tools-ai-sdk/src/tools/index.ts @@ -0,0 +1,3 @@ +export { resolveLibraryId } from "./resolve-library-id"; +export { queryDocs } from "./query-docs"; +export type { Context7ToolsConfig } from "./types"; diff --git a/packages/tools-ai-sdk/src/tools/query-docs.ts b/packages/tools-ai-sdk/src/tools/query-docs.ts new file mode 100644 index 0000000..d07de22 --- /dev/null +++ b/packages/tools-ai-sdk/src/tools/query-docs.ts @@ -0,0 +1,68 @@ +import { tool } from "ai"; +import { z } from "zod"; +import { Context7 } from "@upstash/context7-sdk"; +import type { Context7ToolsConfig } from "./types"; +import { QUERY_DOCS_DESCRIPTION } from "@prompts"; + +/** + * Tool to fetch documentation for a library using its Context7 library ID. + * + * Can be called with or without configuration. Uses CONTEXT7_API_KEY environment + * variable for authentication when no API key is provided. + * + * @param config Optional configuration options + * @returns AI SDK tool for fetching library documentation + * + * @example + * ```typescript + * import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk'; + * import { generateText, stepCountIs } from 'ai'; + * import { openai } from '@ai-sdk/openai'; + * + * const { text } = await generateText({ + * model: openai('gpt-4o'), + * prompt: 'Find React documentation about hooks', + * tools: { + * resolveLibraryId: resolveLibraryId(), + * queryDocs: queryDocs(), + * }, + * stopWhen: stepCountIs(5), + * }); + * ``` + */ +export function queryDocs(config: Context7ToolsConfig = {}) { + const { apiKey } = config; + const getClient = () => new Context7({ apiKey }); + + return tool({ + description: QUERY_DOCS_DESCRIPTION, + inputSchema: z.object({ + libraryId: z + .string() + .describe( + "Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolveLibraryId' or directly from user query in the format '/org/project' or '/org/project/version'." + ), + query: z + .string() + .describe( + "The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query." + ), + }), + execute: async ({ libraryId, query }: { libraryId: string; query: string }) => { + try { + const client = getClient(); + const documentation = await client.getContext(query, libraryId, { type: "txt" }); + + if (!documentation || documentation.length === 0) { + return `No documentation found for library "${libraryId}". This might have happened because you used an invalid Context7-compatible library ID. Use 'resolveLibraryId' to get a valid ID.`; + } + + return documentation; + } catch (error) { + const errorMessage = + error instanceof Error ? error.message : "Failed to fetch documentation"; + return `Error fetching documentation for "${libraryId}": ${errorMessage}`; + } + }, + }); +} diff --git a/packages/tools-ai-sdk/src/tools/resolve-library-id.ts b/packages/tools-ai-sdk/src/tools/resolve-library-id.ts new file mode 100644 index 0000000..4cdc112 --- /dev/null +++ b/packages/tools-ai-sdk/src/tools/resolve-library-id.ts @@ -0,0 +1,67 @@ +import { tool } from "ai"; +import { z } from "zod"; +import { Context7 } from "@upstash/context7-sdk"; +import { RESOLVE_LIBRARY_ID_DESCRIPTION } from "@prompts"; +import type { Context7ToolsConfig } from "./types"; + +/** + * Tool to resolve a library name to a Context7-compatible library ID. + * + * Can be called with or without configuration. Uses CONTEXT7_API_KEY environment + * variable for authentication when no API key is provided. + * + * @param config Optional configuration options + * @returns AI SDK tool for library resolution + * + * @example + * ```typescript + * import { resolveLibraryId, queryDocs } from '@upstash/context7-tools-ai-sdk'; + * import { generateText, stepCountIs } from 'ai'; + * import { openai } from '@ai-sdk/openai'; + * + * const { text } = await generateText({ + * model: openai('gpt-4o'), + * prompt: 'Find React documentation about hooks', + * tools: { + * resolveLibraryId: resolveLibraryId(), + * queryDocs: queryDocs(), + * }, + * stopWhen: stepCountIs(5), + * }); + * ``` + */ +export function resolveLibraryId(config: Context7ToolsConfig = {}) { + const { apiKey } = config; + const getClient = () => new Context7({ apiKey }); + + return tool({ + description: RESOLVE_LIBRARY_ID_DESCRIPTION, + inputSchema: z.object({ + query: z + .string() + .describe( + "The user's original question or task. This is used to rank library results by relevance to what the user is trying to accomplish. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query." + ), + libraryName: z + .string() + .describe( + "Library name to search for and retrieve a Context7-compatible library ID. Use the official library name with proper punctuation — e.g., 'Next.js' instead of 'nextjs', 'Customer.io' instead of 'customerio', 'Three.js' instead of 'threejs'." + ), + }), + execute: async ({ query, libraryName }: { query: string; libraryName: string }) => { + try { + const client = getClient(); + const results = await client.searchLibrary(query, libraryName, { type: "txt" }); + + if (!results || results.length === 0) { + return `No libraries found matching "${libraryName}". Try a different search term or check the library name.`; + } + + return results; + } catch (error) { + const errorMessage = error instanceof Error ? error.message : "Failed to search libraries"; + return `Error searching for libraries: ${errorMessage}. Check your API key and try again.`; + } + }, + }); +} diff --git a/packages/tools-ai-sdk/src/tools/types.ts b/packages/tools-ai-sdk/src/tools/types.ts new file mode 100644 index 0000000..735c9f6 --- /dev/null +++ b/packages/tools-ai-sdk/src/tools/types.ts @@ -0,0 +1,9 @@ +/** + * Configuration for Context7 tools + */ +export interface Context7ToolsConfig { + /** + * Context7 API key. If not provided, will use CONTEXT7_API_KEY environment variable. + */ + apiKey?: string; +} diff --git a/packages/tools-ai-sdk/tsconfig.json b/packages/tools-ai-sdk/tsconfig.json new file mode 100644 index 0000000..67cbe80 --- /dev/null +++ b/packages/tools-ai-sdk/tsconfig.json @@ -0,0 +1,25 @@ +{ + "compilerOptions": { + "lib": ["ESNext"], + "module": "esnext", + "target": "esnext", + "moduleResolution": "bundler", + "moduleDetection": "force", + "allowImportingTsExtensions": true, + "noEmit": true, + "strict": true, + "downlevelIteration": true, + "skipLibCheck": true, + "allowSyntheticDefaultImports": true, + "forceConsistentCasingInFileNames": true, + "allowJs": true, + "baseUrl": ".", + "paths": { + "@tools": ["./src/tools/index.ts"], + "@agents": ["./src/agents/index.ts"], + "@prompts": ["./src/prompts/index.ts"] + } + }, + "include": ["src/**/*", "tsup.config.ts", "vitest.config.ts", "eslint.config.js"], + "exclude": ["node_modules", "dist", "examples"] +} diff --git a/packages/tools-ai-sdk/tsup.config.ts b/packages/tools-ai-sdk/tsup.config.ts new file mode 100644 index 0000000..590d55a --- /dev/null +++ b/packages/tools-ai-sdk/tsup.config.ts @@ -0,0 +1,18 @@ +import { defineConfig } from "tsup"; + +export default defineConfig({ + entry: { + index: "./src/index.ts", + agent: "./src/agents/index.ts", + }, + format: ["cjs", "esm"], + clean: true, + dts: true, + esbuildOptions(options) { + options.alias = { + "@tools": "./src/tools/index.ts", + "@agents": "./src/agents/index.ts", + "@prompts": "./src/prompts/index.ts", + }; + }, +}); diff --git a/packages/tools-ai-sdk/vitest.config.ts b/packages/tools-ai-sdk/vitest.config.ts new file mode 100644 index 0000000..54d0e79 --- /dev/null +++ b/packages/tools-ai-sdk/vitest.config.ts @@ -0,0 +1,20 @@ +import { defineConfig } from "vitest/config"; +import path from "path"; +import { config } from "dotenv"; + +config({ path: path.resolve(__dirname, "../../.env") }); + +export default defineConfig({ + test: { + globals: true, + environment: "node", + include: ["src/**/*.test.ts"], + }, + resolve: { + alias: { + "@tools": path.resolve(__dirname, "./src/tools/index.ts"), + "@agents": path.resolve(__dirname, "./src/agents/index.ts"), + "@prompts": path.resolve(__dirname, "./src/prompts/index.ts"), + }, + }, +}); diff --git a/plugins/claude/context7/.claude-plugin/plugin.json b/plugins/claude/context7/.claude-plugin/plugin.json new file mode 100644 index 0000000..a53438c --- /dev/null +++ b/plugins/claude/context7/.claude-plugin/plugin.json @@ -0,0 +1,7 @@ +{ + "name": "context7", + "description": "Upstash Context7 MCP server for up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.", + "author": { + "name": "Upstash" + } +} diff --git a/plugins/claude/context7/.mcp.json b/plugins/claude/context7/.mcp.json new file mode 100644 index 0000000..38df317 --- /dev/null +++ b/plugins/claude/context7/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY:-}" + } + } + } +} diff --git a/plugins/claude/context7/README.md b/plugins/claude/context7/README.md new file mode 100644 index 0000000..32f77b2 --- /dev/null +++ b/plugins/claude/context7/README.md @@ -0,0 +1,84 @@ +# Context7 Plugin for Claude Code + +Context7 solves a common problem with AI coding assistants: outdated training data and hallucinated APIs. Instead of relying on stale knowledge, Context7 fetches current documentation directly from source repositories. + +## What's Included + +This plugin provides: + +- **MCP Server** - Connects Claude Code to Context7's documentation service +- **Skills** - Auto-triggers documentation lookups when you ask about libraries +- **Agents** - A dedicated `docs-researcher` agent for focused lookups +- **Commands** - `/context7:docs` for manual documentation queries + +## Installation + +Add the marketplace and install the plugin: + +```bash +claude plugin marketplace add upstash/context7 +claude plugin install context7@context7-marketplace +``` + +## API Key (Recommended) + +Without an API key, the plugin connects anonymously and shares the anonymous rate limits. To use your own plan, create an API key in the [Context7 dashboard](https://context7.com/dashboard) and export it as an environment variable before launching Claude Code: + +```bash +# e.g. in ~/.zshrc or ~/.bashrc +export CONTEXT7_API_KEY="your-api-key" +``` + +The plugin's MCP server configuration picks up `CONTEXT7_API_KEY` automatically. Restart Claude Code after setting it, then verify the key is being used by checking your usage in the [dashboard](https://context7.com/dashboard). + +## Available Tools + +### resolve-library-id + +Searches for libraries and returns Context7-compatible identifiers. + +``` +Input: "next.js" +Output: { id: "/vercel/next.js", name: "Next.js", versions: ["v15.1.8", "v14.2.0", ...] } +``` + +### query-docs + +Fetches documentation for a specific library, ranked by relevance to your question. + +``` +Input: { libraryId: "/vercel/next.js", query: "app router middleware" } +Output: Relevant documentation snippets with code examples +``` + +## Usage Examples + +The plugin works automatically when you ask about libraries: + +- "How do I set up authentication in Next.js 15?" +- "Show me React Server Components examples" +- "What's the Prisma syntax for relations?" + +For manual lookups, use the command: + +``` +/context7:docs next.js app router +/context7:docs /vercel/next.js/v15.1.8 middleware +``` + +Or spawn the docs-researcher agent when you want to keep your main context clean: + +``` +spawn docs-researcher to look up Supabase auth methods +``` + +## Version Pinning + +To get documentation for a specific version, include the version in the library ID: + +``` +/vercel/next.js/v15.1.8 +/supabase/supabase/v2.45.0 +``` + +The `resolve-library-id` tool returns available versions, so you can pick the one that matches your project. diff --git a/plugins/claude/context7/agents/docs-researcher.md b/plugins/claude/context7/agents/docs-researcher.md new file mode 100644 index 0000000..ebd408a --- /dev/null +++ b/plugins/claude/context7/agents/docs-researcher.md @@ -0,0 +1,41 @@ +--- +name: docs-researcher +description: Lightweight agent for fetching library documentation without cluttering your main conversation context. +model: sonnet +--- + +You are a documentation researcher specializing in fetching up-to-date library and framework documentation from Context7. + +## Your Task + +When given a question about a library or framework, fetch the relevant documentation and return a concise, actionable answer with code examples. + +## Process + +1. **Identify the library**: Extract the library/framework name from the user's question. + +2. **Resolve the library ID**: Call `resolve-library-id` with: + - `libraryName`: The library name (e.g., "react", "next.js", "prisma") + - `query`: The user's full question for relevance ranking + +3. **Select the best match**: From the results, pick the library with: + - Exact or closest name match + - Highest benchmark score + - Appropriate version if the user specified one (e.g., "React 19" → look for v19.x) + +4. **Fetch documentation**: Call `query-docs` with: + - `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`) + - `query`: The user's specific question for targeted results, scoped to a single concept + +5. **Return a focused answer**: Summarize the relevant documentation with: + - Direct answer to the question + - Code examples from the docs + - Links or references if available + +## Guidelines + +- Pass the user's full question as the query parameter for better relevance, but keep each query to a single concept +- If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic +- When the user mentions a version (e.g., "Next.js 15"), use version-specific library IDs if available +- If `resolve-library-id` returns multiple matches, prefer official/primary packages over community forks +- Keep responses concise - the goal is to answer the question, not dump entire documentation diff --git a/plugins/claude/context7/commands/docs.md b/plugins/claude/context7/commands/docs.md new file mode 100644 index 0000000..1e6415d --- /dev/null +++ b/plugins/claude/context7/commands/docs.md @@ -0,0 +1,45 @@ +--- +description: Look up documentation for any library +argument-hint: [query] +--- + +# /context7:docs + +Fetches up-to-date documentation and code examples for a library. + +## Usage + +``` +/context7:docs [query] +``` + +- **library**: The library name, or a Context7 ID starting with `/` +- **query**: What you're looking for (optional but recommended; run the command once per distinct concept, unless asking how they interact) + +## Examples + +``` +/context7:docs react hooks +/context7:docs next.js authentication +/context7:docs prisma relations +/context7:docs /vercel/next.js/v15.1.8 app router +/context7:docs /supabase/supabase row level security +``` + +## How It Works + +1. If the library starts with `/`, it's used directly as the Context7 ID +2. Otherwise, `resolve-library-id` finds the best matching library +3. `query-docs` fetches documentation relevant to your query +4. Results include code examples and explanations + +## Version-Specific Lookups + +Include the version in the library ID for pinned documentation: + +``` +/context7:docs /vercel/next.js/v15.1.8 middleware +/context7:docs /facebook/react/v19.0.0 use hook +``` + +This is useful when you're working with a specific version and want docs that match exactly. diff --git a/plugins/claude/context7/skills/context7-mcp/SKILL.md b/plugins/claude/context7/skills/context7-mcp/SKILL.md new file mode 100644 index 0000000..245b080 --- /dev/null +++ b/plugins/claude/context7/skills/context7-mcp/SKILL.md @@ -0,0 +1,56 @@ +--- +name: context7-mcp +description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc. +--- + +When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data. + +## When to Use This Skill + +Activate this skill when the user: + +- Asks setup or configuration questions ("How do I configure Next.js middleware?") +- Requests code involving libraries ("Write a Prisma query for...") +- Needs API references ("What are the Supabase auth methods?") +- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## How to Fetch Documentation + +### Step 1: Resolve the Library ID + +Call `resolve-library-id` with: + +- `libraryName`: The library name extracted from the user's question +- `query`: The user's full question (improves relevance ranking) + +### Step 2: Select the Best Match + +From the resolution results, choose based on: + +- Exact or closest name match to what the user asked for +- Higher benchmark scores indicate better documentation quality +- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs + +### Step 3: Fetch the Documentation + +Call `query-docs` with: + +- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`) +- `query`: The user's specific question, scoped to a single concept + +If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic. + +### Step 4: Use the Documentation + +Incorporate the fetched documentation into your response: + +- Answer the user's question using current, accurate information +- Include relevant code examples from the docs +- Cite the library version when relevant + +## Guidelines + +- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact +- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step +- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks diff --git a/plugins/codex/context7/.codex-plugin/plugin.json b/plugins/codex/context7/.codex-plugin/plugin.json new file mode 100644 index 0000000..f4c63be --- /dev/null +++ b/plugins/codex/context7/.codex-plugin/plugin.json @@ -0,0 +1,32 @@ +{ + "name": "context7", + "version": "1.0.1", + "description": "Upstash Context7 MCP server for up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.", + "author": { + "name": "Upstash", + "email": "context7@upstash.com", + "url": "https://upstash.com" + }, + "homepage": "https://context7.com", + "repository": "https://github.com/upstash/context7", + "license": "MIT", + "keywords": ["documentation", "context", "mcp", "library-docs"], + "skills": "./skills/", + "mcpServers": "./.mcp.json", + "interface": { + "displayName": "Context7", + "shortDescription": "Fetch current library documentation in Codex", + "longDescription": "Context7 adds current, version-aware library documentation and code examples to Codex through the Context7 MCP server.", + "developerName": "Upstash", + "category": "Developer Tools", + "capabilities": ["Read"], + "websiteURL": "https://context7.com", + "privacyPolicyURL": "https://upstash.com/privacy", + "termsOfServiceURL": "https://upstash.com/terms", + "defaultPrompt": [ + "Use Context7 for Next.js middleware docs.", + "Find current Prisma relation query examples." + ], + "brandColor": "#059669" + } +} diff --git a/plugins/codex/context7/.mcp.json b/plugins/codex/context7/.mcp.json new file mode 100644 index 0000000..c5280c5 --- /dev/null +++ b/plugins/codex/context7/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } +} diff --git a/plugins/codex/context7/README.md b/plugins/codex/context7/README.md new file mode 100644 index 0000000..0eaa412 --- /dev/null +++ b/plugins/codex/context7/README.md @@ -0,0 +1,77 @@ +# Context7 Plugin for Codex + +Context7 solves a common problem with AI coding assistants: outdated training data and hallucinated APIs. Instead of relying on stale knowledge, Context7 fetches current documentation directly from source repositories. + +## Installation + +Add the Context7 marketplace and install the plugin: + +```bash +codex plugin marketplace add upstash/context7 +codex plugin add context7@context7-marketplace +``` + +After adding the plugin, a browser window opens so you can log in to Context7 via OAuth. Start a new Codex thread after installation so Codex can load the plugin's skill and MCP tools. + +## What's Included + +This plugin provides: + +- **MCP Server** - Connects Codex to Context7's documentation service +- **Skills** - Auto-triggers documentation lookups when you ask about libraries + +## Authentication + +The plugin connects to the hosted Context7 MCP server: + +```json +{ + "type": "http", + "url": "https://mcp.context7.com/mcp" +} +``` + +When you add the plugin, a browser window opens to log in to Context7 via OAuth, so your requests use your account's authenticated rate limits. On remote or headless machines where a browser can't open, run `npx ctx7 setup --codex` instead — it uses the OAuth device flow and writes an API-key-backed configuration to `~/.codex/config.toml`. Create or manage API keys in the [Context7 dashboard](https://context7.com/dashboard). + +## Available Tools + +### resolve-library-id + +Searches for libraries and returns Context7-compatible identifiers. + +```text +Input: "next.js" +Output: { id: "/vercel/next.js", name: "Next.js", versions: ["v15.1.8", "v14.2.0", ...] } +``` + +### query-docs + +Fetches documentation for a specific library, ranked by relevance to your question. + +```text +Input: { libraryId: "/vercel/next.js", query: "app router middleware" } +Output: Relevant documentation snippets with code examples +``` + +## Usage Examples + +The bundled skill works automatically when you ask about libraries: + +- "How do I set up authentication in Next.js 15?" +- "Show me React Server Components examples" +- "What's the Prisma syntax for relations?" + +You can also invoke it explicitly: + +```text +use context7 for Next.js middleware docs +use context7 for Prisma query examples with relations +use context7 for the Supabase syntax for row-level security +``` + +To get documentation for a specific version, include the version in the library ID: + +```text +/vercel/next.js/v15.1.8 +/supabase/supabase/v2.45.0 +``` diff --git a/plugins/codex/context7/skills/context7-mcp/SKILL.md b/plugins/codex/context7/skills/context7-mcp/SKILL.md new file mode 100644 index 0000000..245b080 --- /dev/null +++ b/plugins/codex/context7/skills/context7-mcp/SKILL.md @@ -0,0 +1,56 @@ +--- +name: context7-mcp +description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc. +--- + +When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data. + +## When to Use This Skill + +Activate this skill when the user: + +- Asks setup or configuration questions ("How do I configure Next.js middleware?") +- Requests code involving libraries ("Write a Prisma query for...") +- Needs API references ("What are the Supabase auth methods?") +- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## How to Fetch Documentation + +### Step 1: Resolve the Library ID + +Call `resolve-library-id` with: + +- `libraryName`: The library name extracted from the user's question +- `query`: The user's full question (improves relevance ranking) + +### Step 2: Select the Best Match + +From the resolution results, choose based on: + +- Exact or closest name match to what the user asked for +- Higher benchmark scores indicate better documentation quality +- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs + +### Step 3: Fetch the Documentation + +Call `query-docs` with: + +- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`) +- `query`: The user's specific question, scoped to a single concept + +If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic. + +### Step 4: Use the Documentation + +Incorporate the fetched documentation into your response: + +- Answer the user's question using current, accurate information +- Include relevant code examples from the docs +- Cite the library version when relevant + +## Guidelines + +- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact +- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step +- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks diff --git a/plugins/context7-power/POWER.md b/plugins/context7-power/POWER.md new file mode 100644 index 0000000..b6759e4 --- /dev/null +++ b/plugins/context7-power/POWER.md @@ -0,0 +1,78 @@ +--- +name: "context7" +displayName: "Context7" +description: "Find up-to-date documentation, API references, and code examples for libraries, frameworks, SDKs, and developer tools using Context7." +keywords: ["context7", "library docs", "framework docs", "sdk docs", "api reference", "code examples", "package docs"] +author: "Context7" +--- + +# Context7 + +## Overview + +Context7 is a documentation power for libraries, frameworks, SDKs, APIs, and developer tools. It retrieves up-to-date documentation to ground code generation. + +## When to Use This Power + +Use this Power when the user: + +- Asks setup or configuration questions about a library, framework, SDK, API, CLI tool, or cloud service +- Requests code involving a specific library or framework +- Needs API references or current documentation +- Mentions a framework, SDK, or developer tool by name +- Needs help with version migrations, library-specific debugging, or CLI usage + +Do not use this Power for refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts. + +## Usage + +### Step 1: Resolve the Library ID + +Call `resolve-library-id` with: + +- `libraryName`: The library name extracted from the user's question +- `query`: The user's full question (improves relevance ranking) + +Always start with `resolve-library-id` using the library name and the user's question, unless the user provides an exact library ID in `/org/project` format + +### Step 2: Select the Best Match + +From the resolution results, choose based on: + +- Exact or closest name match to what the user asked for +- Higher benchmark scores indicate better documentation quality +- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs +- If the results do not look right, try alternate names or rephrase the query + +### Step 3: Fetch the Documentation + +Call `query-docs` with: + +- `libraryId`: The selected Context7 library ID (e.g., /vercel/next.js) +- `query`: The user's full, specific question rather than a single word, scoped to a single concept + +If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic. + +### Step 4: Use the Documentation + +Incorporate the fetched documentation into your response: + +- Answer the user's question using current, accurate information +- Include relevant code examples from the docs +- Cite the library version when relevant + +## Best Practices + +- Pass the user's full question as the query for better results, but keep each query to a single concept +- Keep each query to one topic; split multi-topic questions into separate `query-docs` calls, unless the question is about how the concepts interact +- When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step +- When multiple matches exist, prefer official/primary packages over community forks +- Use this Power for API syntax, configuration, setup instructions, version migration, library-specific debugging, and CLI tool usage +- Use Context7 even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs. +- Do not use Context7 for refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts. + +## License and Support + +This power integrates with the Context7 MCP Server (MIT License). +- [Privacy Policy](https://upstash.com/trust/context7addendum.pdf) +- [Support](mailto:context7@upstash.com) \ No newline at end of file diff --git a/plugins/context7-power/mcp.json b/plugins/context7-power/mcp.json new file mode 100644 index 0000000..a101560 --- /dev/null +++ b/plugins/context7-power/mcp.json @@ -0,0 +1,7 @@ +{ + "mcpServers": { + "context7": { + "url": "https://mcp.context7.com/mcp" + } + } +} diff --git a/plugins/copilot/context7/.mcp.json b/plugins/copilot/context7/.mcp.json new file mode 100644 index 0000000..38df317 --- /dev/null +++ b/plugins/copilot/context7/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { + "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY:-}" + } + } + } +} diff --git a/plugins/copilot/context7/README.md b/plugins/copilot/context7/README.md new file mode 100644 index 0000000..3052097 --- /dev/null +++ b/plugins/copilot/context7/README.md @@ -0,0 +1,84 @@ +# Context7 Plugin for GitHub Copilot CLI + +Context7 solves a common problem with AI coding assistants: outdated training data and hallucinated APIs. Instead of relying on stale knowledge, Context7 fetches current documentation directly from source repositories. + +## What's Included + +This plugin provides: + +- **MCP Server** - Connects Copilot CLI to Context7's documentation service +- **Skills** - Auto-triggers documentation lookups when you ask about libraries +- **Agents** - A dedicated `docs-researcher` agent for focused lookups +- **Commands** - `/context7:docs` for manual documentation queries + +## Installation + +Add the marketplace and install the plugin: + +```bash +copilot plugin marketplace add upstash/context7 +copilot plugin install context7@context7-marketplace +``` + +## API Key (Recommended) + +Without an API key, the plugin connects anonymously and shares the anonymous rate limits. To use your own plan, create an API key in the [Context7 dashboard](https://context7.com/dashboard) and export it as an environment variable before launching Copilot CLI: + +```bash +# e.g. in ~/.zshrc or ~/.bashrc +export CONTEXT7_API_KEY="your-api-key" +``` + +The plugin's MCP server configuration picks up `CONTEXT7_API_KEY` automatically. Restart Copilot CLI after setting it, then verify the key is being used by checking your usage in the [dashboard](https://context7.com/dashboard). + +## Available Tools + +### resolve-library-id + +Searches for libraries and returns Context7-compatible identifiers. + +``` +Input: "next.js" +Output: { id: "/vercel/next.js", name: "Next.js", versions: ["v15.1.8", "v14.2.0", ...] } +``` + +### query-docs + +Fetches documentation for a specific library, ranked by relevance to your question. + +``` +Input: { libraryId: "/vercel/next.js", query: "app router middleware" } +Output: Relevant documentation snippets with code examples +``` + +## Usage Examples + +The plugin works automatically when you ask about libraries: + +- "How do I set up authentication in Next.js 15?" +- "Show me React Server Components examples" +- "What's the Prisma syntax for relations?" + +For manual lookups, use the command: + +``` +/context7:docs next.js app router +/context7:docs /vercel/next.js/v15.1.8 middleware +``` + +Or use the docs-researcher agent when you want to keep your main context clean: + +```bash +copilot --agent docs-researcher -p "look up Supabase auth methods" +``` + +## Version Pinning + +To get documentation for a specific version, include the version in the library ID: + +``` +/vercel/next.js/v15.1.8 +/supabase/supabase/v2.45.0 +``` + +The `resolve-library-id` tool returns available versions, so you can pick the one that matches your project. diff --git a/plugins/copilot/context7/agents/docs-researcher.agent.md b/plugins/copilot/context7/agents/docs-researcher.agent.md new file mode 100644 index 0000000..de3309b --- /dev/null +++ b/plugins/copilot/context7/agents/docs-researcher.agent.md @@ -0,0 +1,40 @@ +--- +name: docs-researcher +description: Lightweight agent for fetching library documentation without cluttering your main conversation context. +--- + +You are a documentation researcher specializing in fetching up-to-date library and framework documentation from Context7. + +## Your Task + +When given a question about a library or framework, fetch the relevant documentation and return a concise, actionable answer with code examples. + +## Process + +1. **Identify the library**: Extract the library/framework name from the user's question. + +2. **Resolve the library ID**: Call `resolve-library-id` with: + - `libraryName`: The library name (e.g., "react", "next.js", "prisma") + - `query`: The user's full question for relevance ranking + +3. **Select the best match**: From the results, pick the library with: + - Exact or closest name match + - Highest benchmark score + - Appropriate version if the user specified one (e.g., "React 19" → look for v19.x) + +4. **Fetch documentation**: Call `query-docs` with: + - `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`) + - `query`: The user's specific question for targeted results, scoped to a single concept + +5. **Return a focused answer**: Summarize the relevant documentation with: + - Direct answer to the question + - Code examples from the docs + - Links or references if available + +## Guidelines + +- Pass the user's full question as the query parameter for better relevance, but keep each query to a single concept +- If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic +- When the user mentions a version (e.g., "Next.js 15"), use version-specific library IDs if available +- If `resolve-library-id` returns multiple matches, prefer official/primary packages over community forks +- Keep responses concise - the goal is to answer the question, not dump entire documentation diff --git a/plugins/copilot/context7/commands/docs.md b/plugins/copilot/context7/commands/docs.md new file mode 100644 index 0000000..e3494dd --- /dev/null +++ b/plugins/copilot/context7/commands/docs.md @@ -0,0 +1,44 @@ +--- +description: Look up documentation for any library +--- + +# /context7:docs + +Fetches up-to-date documentation and code examples for a library. + +## Usage + +``` +/context7:docs [query] +``` + +- **library**: The library name, or a Context7 ID starting with `/` +- **query**: What you're looking for (optional but recommended; run the command once per distinct concept, unless asking how they interact) + +## Examples + +``` +/context7:docs react hooks +/context7:docs next.js authentication +/context7:docs prisma relations +/context7:docs /vercel/next.js/v15.1.8 app router +/context7:docs /supabase/supabase row level security +``` + +## How It Works + +1. If the library starts with `/`, it's used directly as the Context7 ID +2. Otherwise, `resolve-library-id` finds the best matching library +3. `query-docs` fetches documentation relevant to your query +4. Results include code examples and explanations + +## Version-Specific Lookups + +Include the version in the library ID for pinned documentation: + +``` +/context7:docs /vercel/next.js/v15.1.8 middleware +/context7:docs /facebook/react/v19.0.0 use hook +``` + +This is useful when you're working with a specific version and want docs that match exactly. diff --git a/plugins/copilot/context7/plugin.json b/plugins/copilot/context7/plugin.json new file mode 100644 index 0000000..191088d --- /dev/null +++ b/plugins/copilot/context7/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "context7", + "description": "Upstash Context7 MCP server for up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.", + "version": "1.0.2", + "author": { + "name": "Upstash" + }, + "license": "MIT", + "keywords": ["documentation", "context", "mcp", "library-docs"], + "repository": "https://github.com/upstash/context7", + "agents": "agents/", + "skills": "skills/", + "commands": "commands/", + "mcpServers": ".mcp.json" +} diff --git a/plugins/copilot/context7/skills/context7-mcp/SKILL.md b/plugins/copilot/context7/skills/context7-mcp/SKILL.md new file mode 100644 index 0000000..245b080 --- /dev/null +++ b/plugins/copilot/context7/skills/context7-mcp/SKILL.md @@ -0,0 +1,56 @@ +--- +name: context7-mcp +description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc. +--- + +When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data. + +## When to Use This Skill + +Activate this skill when the user: + +- Asks setup or configuration questions ("How do I configure Next.js middleware?") +- Requests code involving libraries ("Write a Prisma query for...") +- Needs API references ("What are the Supabase auth methods?") +- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## How to Fetch Documentation + +### Step 1: Resolve the Library ID + +Call `resolve-library-id` with: + +- `libraryName`: The library name extracted from the user's question +- `query`: The user's full question (improves relevance ranking) + +### Step 2: Select the Best Match + +From the resolution results, choose based on: + +- Exact or closest name match to what the user asked for +- Higher benchmark scores indicate better documentation quality +- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs + +### Step 3: Fetch the Documentation + +Call `query-docs` with: + +- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`) +- `query`: The user's specific question, scoped to a single concept + +If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic. + +### Step 4: Use the Documentation + +Incorporate the fetched documentation into your response: + +- Answer the user's question using current, accurate information +- Include relevant code examples from the docs +- Cite the library version when relevant + +## Guidelines + +- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact +- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step +- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks diff --git a/plugins/cursor/context7/.cursor/plugin.json b/plugins/cursor/context7/.cursor/plugin.json new file mode 100644 index 0000000..8692c4f --- /dev/null +++ b/plugins/cursor/context7/.cursor/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "context7", + "version": "1.0.0", + "description": "Upstash Context7 MCP server for up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.", + "author": { + "name": "Context7", + "email": "context7@upstash.com", + "url": "https://context7.com" + }, + "keywords": ["documentation", "mcp", "context7", "libraries", "frameworks"], + "logo": "https://context7.com/brand/context7-icon-green.svg", + "primaryColor": "#059669" +} diff --git a/plugins/cursor/context7/README.md b/plugins/cursor/context7/README.md new file mode 100644 index 0000000..20daded --- /dev/null +++ b/plugins/cursor/context7/README.md @@ -0,0 +1,53 @@ +# Context7 Plugin for Cursor + +Context7 solves a common problem with AI coding assistants: outdated training data and hallucinated APIs. Instead of relying on stale knowledge, Context7 fetches current documentation directly from source repositories. + +## What's Included + +This plugin provides: + +- **MCP Server** — Connects Cursor to Context7's documentation service +- **Rules** — An always-on `use-context7` rule that nudges the agent to fetch docs when unsure about library APIs +- **Skills** — A `context7-docs-lookup` skill with detailed instructions on resolving libraries and fetching documentation +- **Agents** — A dedicated `docs-researcher` agent for focused lookups + +## Available Tools + +### resolve-library-id + +Searches for libraries and returns Context7-compatible identifiers. + +``` +Input: "next.js" +Output: { id: "/vercel/next.js", name: "Next.js", versions: ["v15.1.8", "v14.2.0", ...] } +``` + +### query-docs + +Fetches documentation for a specific library, ranked by relevance to your question. + +``` +Input: { libraryId: "/vercel/next.js", query: "app router middleware" } +Output: Relevant documentation snippets with code examples +``` + +## Usage Examples + +The plugin works automatically when you ask about libraries: + +- "How do I set up authentication in Next.js 15?" +- "Show me React Server Components examples" +- "What's the Prisma syntax for relations?" + +Or use the docs-researcher agent when you want to keep your main context clean. + +## Version Pinning + +To get documentation for a specific version, include the version in the library ID: + +``` +/vercel/next.js/v15.1.8 +/supabase/supabase/v2.45.0 +``` + +The `resolve-library-id` tool returns available versions, so you can pick the one that matches your project. diff --git a/plugins/cursor/context7/agents/docs-researcher.md b/plugins/cursor/context7/agents/docs-researcher.md new file mode 100644 index 0000000..de3309b --- /dev/null +++ b/plugins/cursor/context7/agents/docs-researcher.md @@ -0,0 +1,40 @@ +--- +name: docs-researcher +description: Lightweight agent for fetching library documentation without cluttering your main conversation context. +--- + +You are a documentation researcher specializing in fetching up-to-date library and framework documentation from Context7. + +## Your Task + +When given a question about a library or framework, fetch the relevant documentation and return a concise, actionable answer with code examples. + +## Process + +1. **Identify the library**: Extract the library/framework name from the user's question. + +2. **Resolve the library ID**: Call `resolve-library-id` with: + - `libraryName`: The library name (e.g., "react", "next.js", "prisma") + - `query`: The user's full question for relevance ranking + +3. **Select the best match**: From the results, pick the library with: + - Exact or closest name match + - Highest benchmark score + - Appropriate version if the user specified one (e.g., "React 19" → look for v19.x) + +4. **Fetch documentation**: Call `query-docs` with: + - `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`) + - `query`: The user's specific question for targeted results, scoped to a single concept + +5. **Return a focused answer**: Summarize the relevant documentation with: + - Direct answer to the question + - Code examples from the docs + - Links or references if available + +## Guidelines + +- Pass the user's full question as the query parameter for better relevance, but keep each query to a single concept +- If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic +- When the user mentions a version (e.g., "Next.js 15"), use version-specific library IDs if available +- If `resolve-library-id` returns multiple matches, prefer official/primary packages over community forks +- Keep responses concise - the goal is to answer the question, not dump entire documentation diff --git a/plugins/cursor/context7/mcp.json b/plugins/cursor/context7/mcp.json new file mode 100644 index 0000000..734b324 --- /dev/null +++ b/plugins/cursor/context7/mcp.json @@ -0,0 +1,5 @@ +{ + "context7": { + "url": "https://mcp.context7.com/mcp/oauth" + } +} diff --git a/plugins/cursor/context7/rules/use-context7.mdc b/plugins/cursor/context7/rules/use-context7.mdc new file mode 100644 index 0000000..b1b88cd --- /dev/null +++ b/plugins/cursor/context7/rules/use-context7.mdc @@ -0,0 +1,18 @@ +--- +description: Use Context7 MCP to fetch up-to-date documentation when unsure about library APIs, syntax, or behavior instead of guessing from training data. +alwaysApply: true +--- + +When you're unsure about a library's API, syntax, configuration, or behavior, use Context7 to fetch current documentation rather than guessing from training data that may be outdated. + +Use Context7 when: +- You're not confident about the exact API or syntax for a library +- The user asks about a specific version (e.g., "Next.js 15", "React 19") +- The library or framework has had recent major changes +- You need accurate code examples for a specific use case + +You don't need to use Context7 for: +- Well-established language features (e.g., JavaScript array methods, Python builtins) +- Conversations where the user has already provided the relevant code or docs + +See the `context7-docs-lookup` skill for detailed instructions on how to resolve libraries and fetch documentation. diff --git a/plugins/cursor/context7/skills/context7-mcp/SKILL.md b/plugins/cursor/context7/skills/context7-mcp/SKILL.md new file mode 100644 index 0000000..245b080 --- /dev/null +++ b/plugins/cursor/context7/skills/context7-mcp/SKILL.md @@ -0,0 +1,56 @@ +--- +name: context7-mcp +description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc. +--- + +When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data. + +## When to Use This Skill + +Activate this skill when the user: + +- Asks setup or configuration questions ("How do I configure Next.js middleware?") +- Requests code involving libraries ("Write a Prisma query for...") +- Needs API references ("What are the Supabase auth methods?") +- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## How to Fetch Documentation + +### Step 1: Resolve the Library ID + +Call `resolve-library-id` with: + +- `libraryName`: The library name extracted from the user's question +- `query`: The user's full question (improves relevance ranking) + +### Step 2: Select the Best Match + +From the resolution results, choose based on: + +- Exact or closest name match to what the user asked for +- Higher benchmark scores indicate better documentation quality +- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs + +### Step 3: Fetch the Documentation + +Call `query-docs` with: + +- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`) +- `query`: The user's specific question, scoped to a single concept + +If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic. + +### Step 4: Use the Documentation + +Incorporate the fetched documentation into your response: + +- Answer the user's question using current, accurate information +- Include relevant code examples from the docs +- Cite the library version when relevant + +## Guidelines + +- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact +- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step +- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml new file mode 100644 index 0000000..4845a55 --- /dev/null +++ b/pnpm-lock.yaml @@ -0,0 +1,6249 @@ +lockfileVersion: '9.0' + +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + +importers: + + .: + dependencies: + '@inquirer/core': + specifier: ^11.1.1 + version: 11.1.1(@types/node@25.0.3) + '@inquirer/type': + specifier: ^4.0.3 + version: 4.0.3(@types/node@25.0.3) + devDependencies: + '@changesets/cli': + specifier: ^2.29.8 + version: 2.29.8(@types/node@25.0.3) + '@types/node': + specifier: ^25.0.3 + version: 25.0.3 + '@typescript-eslint/eslint-plugin': + specifier: ^8.28.0 + version: 8.47.0(@typescript-eslint/parser@8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + '@typescript-eslint/parser': + specifier: ^8.28.0 + version: 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + eslint: + specifier: ^9.34.0 + version: 9.39.4(jiti@2.7.0) + eslint-config-prettier: + specifier: ^10.1.1 + version: 10.1.8(eslint@9.39.4(jiti@2.7.0)) + eslint-plugin-prettier: + specifier: ^5.5.6 + version: 5.5.6(eslint-config-prettier@10.1.8(eslint@9.39.4(jiti@2.7.0)))(eslint@9.39.4(jiti@2.7.0))(prettier@3.6.2) + prettier: + specifier: ^3.6.2 + version: 3.6.2 + typescript: + specifier: ^5.8.2 + version: 5.9.3 + typescript-eslint: + specifier: ^8.28.0 + version: 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + + packages/cli: + dependencies: + '@inquirer/core': + specifier: ^11.1.1 + version: 11.1.1(@types/node@22.19.7) + '@inquirer/prompts': + specifier: ^8.2.0 + version: 8.2.0(@types/node@22.19.7) + boxen: + specifier: ^8.0.1 + version: 8.0.1 + commander: + specifier: ^15.0.0 + version: 15.0.0 + figlet: + specifier: ^1.9.4 + version: 1.9.4 + open: + specifier: ^10.1.0 + version: 10.2.0 + ora: + specifier: ^9.4.0 + version: 9.4.0 + picocolors: + specifier: ^1.1.1 + version: 1.1.1 + devDependencies: + '@types/figlet': + specifier: ^1.7.0 + version: 1.7.0 + '@types/node': + specifier: ^22.19.1 + version: 22.19.7 + '@typescript-eslint/eslint-plugin': + specifier: ^8.28.0 + version: 8.47.0(@typescript-eslint/parser@8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + '@typescript-eslint/parser': + specifier: ^8.28.0 + version: 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + eslint: + specifier: ^9.34.0 + version: 9.39.4(jiti@2.7.0) + eslint-plugin-prettier: + specifier: ^5.5.6 + version: 5.5.6(eslint-config-prettier@10.1.8(eslint@9.39.4(jiti@2.7.0)))(eslint@9.39.4(jiti@2.7.0))(prettier@3.6.2) + prettier: + specifier: ^3.6.2 + version: 3.6.2 + tsup: + specifier: ^8.5.0 + version: 8.5.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0) + typescript: + specifier: ^5.8.2 + version: 5.9.3 + typescript-eslint: + specifier: ^8.28.0 + version: 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + vitest: + specifier: ^4.1.9 + version: 4.1.9(@opentelemetry/api@1.9.0)(@types/node@22.19.7)(vite@7.2.4(@types/node@22.19.7)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)) + + packages/mcp: + dependencies: + '@modelcontextprotocol/sdk': + specifier: ^1.29.0 + version: 1.29.0(zod@4.4.3) + '@types/express': + specifier: ^5.0.4 + version: 5.0.5 + '@upstash/redis': + specifier: ^1.38.0 + version: 1.38.0 + commander: + specifier: ^13.1.0 + version: 13.1.0 + express: + specifier: ^5.1.0 + version: 5.1.0 + jose: + specifier: ^6.2.3 + version: 6.2.3 + undici: + specifier: ^6.26.0 + version: 6.26.0 + zod: + specifier: ^4.4.3 + version: 4.4.3 + devDependencies: + '@types/node': + specifier: ^25.0.3 + version: 25.0.3 + typescript: + specifier: ^5.8.2 + version: 5.9.3 + vitest: + specifier: ^4.1.9 + version: 4.1.9(@opentelemetry/api@1.9.0)(@types/node@25.0.3)(vite@7.2.4(@types/node@25.0.3)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)) + + packages/pi: + devDependencies: + '@earendil-works/pi-coding-agent': + specifier: ^0.78.0 + version: 0.78.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.20.1)(zod@4.4.3) + '@types/node': + specifier: ^25.9.1 + version: 25.9.1 + dotenv: + specifier: ^17.4.2 + version: 17.4.2 + typebox: + specifier: ^1.1.38 + version: 1.1.38 + typescript: + specifier: ^5.9.3 + version: 5.9.3 + vitest: + specifier: ^4.1.9 + version: 4.1.9(@opentelemetry/api@1.9.0)(@types/node@25.9.1)(vite@7.2.4(@types/node@25.9.1)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)) + + packages/sdk: + devDependencies: + '@types/node': + specifier: ^25.0.3 + version: 25.0.3 + dotenv: + specifier: ^17.4.2 + version: 17.4.2 + tsup: + specifier: ^8.5.1 + version: 8.5.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0) + typescript: + specifier: ^5.8.2 + version: 5.9.3 + vitest: + specifier: ^4.1.9 + version: 4.1.9(@opentelemetry/api@1.9.0)(@types/node@25.0.3)(vite@7.2.4(@types/node@25.0.3)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)) + + packages/tools-ai-sdk: + devDependencies: + '@ai-sdk/amazon-bedrock': + specifier: ^4.0.9 + version: 4.0.12(zod@4.4.3) + '@types/node': + specifier: ^25.0.3 + version: 25.0.3 + '@upstash/context7-sdk': + specifier: workspace:* + version: link:../sdk + ai: + specifier: ^6.0.5 + version: 6.0.23(zod@4.4.3) + dotenv: + specifier: ^17.4.2 + version: 17.4.2 + tsup: + specifier: ^8.5.1 + version: 8.5.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0) + typescript: + specifier: ^5.8.2 + version: 5.9.3 + vitest: + specifier: ^4.1.9 + version: 4.1.9(@opentelemetry/api@1.9.0)(@types/node@25.0.3)(vite@7.2.4(@types/node@25.0.3)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)) + zod: + specifier: ^4.4.3 + version: 4.4.3 + +packages: + + '@ai-sdk/amazon-bedrock@4.0.12': + resolution: {integrity: sha512-5NvAnCa8mQy9bxWv8tMR8u77fcOhXnxozxRtjB/to69RBFyy4ncxsTHhJEK3ypHEvaYHheBkAxSOwzEu79dW3A==} + engines: {node: '>=18'} + peerDependencies: + zod: ^3.25.76 || ^4.1.8 + + '@ai-sdk/anthropic@3.0.9': + resolution: {integrity: sha512-QBD4qDnwIHd+N5PpjxXOaWJig1aRB43J0PM5ZUe6Yyl9Qq2bUmraQjvNznkuFKy+hMFDgj0AvgGogTiO5TC+qA==} + engines: {node: '>=18'} + peerDependencies: + zod: ^3.25.76 || ^4.1.8 + + '@ai-sdk/gateway@3.0.10': + resolution: {integrity: sha512-sRlPMKd38+fdp2y11USW44c0o8tsIsT6T/pgyY04VXC3URjIRnkxugxd9AkU2ogfpPDMz50cBAGPnMxj+6663Q==} + engines: {node: '>=18'} + peerDependencies: + zod: ^3.25.76 || ^4.1.8 + + '@ai-sdk/provider-utils@4.0.4': + resolution: {integrity: sha512-VxhX0B/dWGbpNHxrKCWUAJKXIXV015J4e7qYjdIU9lLWeptk0KMLGcqkB4wFxff5Njqur8dt8wRi1MN9lZtDqg==} + engines: {node: '>=18'} + peerDependencies: + zod: ^3.25.76 || ^4.1.8 + + '@ai-sdk/provider@3.0.2': + resolution: {integrity: sha512-HrEmNt/BH/hkQ7zpi2o6N3k1ZR1QTb7z85WYhYygiTxOQuaml4CMtHCWRbric5WPU+RNsYI7r1EpyVQMKO1pYw==} + engines: {node: '>=18'} + + '@anthropic-ai/sdk@0.91.1': + resolution: {integrity: sha512-LAmu761tSN9r66ixvmciswUj/ZC+1Q4iAfpedTfSVLeswRwnY3n2Nb6Tsk+cLPP28aLOPWeMgIuTuCcMC6W/iw==} + hasBin: true + peerDependencies: + zod: ^3.25.0 || ^4.0.0 + peerDependenciesMeta: + zod: + optional: true + + '@aws-crypto/crc32@5.2.0': + resolution: {integrity: sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg==} + engines: {node: '>=16.0.0'} + + '@aws-crypto/sha256-browser@5.2.0': + resolution: {integrity: sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw==} + + '@aws-crypto/sha256-js@5.2.0': + resolution: {integrity: sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA==} + engines: {node: '>=16.0.0'} + + '@aws-crypto/supports-web-crypto@5.2.0': + resolution: {integrity: sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg==} + + '@aws-crypto/util@5.2.0': + resolution: {integrity: sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ==} + + '@aws-sdk/client-bedrock-runtime@3.1048.0': + resolution: {integrity: sha512-u+NT61JZEkRFtpL0CAw1N1dwxnaLgwVXQl/zjJxTGgLyS/jTIdg2SdoEoCTHxgDyCnqa1HEi9QOoE9/pYRNpOQ==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/core@3.974.13': + resolution: {integrity: sha512-+Y5/4tHki0uYgyx8eun146DegRVQBpdKGK5RbV0FTKJPpaKTchvqVxrrRFK6Wk0JksO4iAZKw3eqxGEIwtO98w==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/credential-provider-env@3.972.39': + resolution: {integrity: sha512-29wX9zpAvEt1vcj0psha+y6ygBHy2V/S72mp6e7q0KARLWXq+pwE/lR6qGkwknQvruh52lXvlqZIga8Hdxkucw==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/credential-provider-http@3.972.41': + resolution: {integrity: sha512-IA3CQTjtJkb6u1H4mE4936c8OPBMa9Jggtwe8U2Mqw/vvb/tZ5Ebd0mcZcX0uKWQhOyYo/+qNIwkV5Xh+FeJJA==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/credential-provider-ini@3.972.43': + resolution: {integrity: sha512-4mzII+3mZEVXXE1xzrLQrCJL7/r62A63bA6SVzZoNL5rqCJghpf+xgGltVrIBBs0n+mOZBKrQl2tRREtvZ5l6A==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/credential-provider-login@3.972.43': + resolution: {integrity: sha512-HG7kQCwXtbv3oBV61Ins0oNX8KKyvrMqqRkb6ZiAfQHbMuHaiNaEb2KnpKLPkNpqImSBK82UkVE/kaY6IfWikA==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/credential-provider-node@3.972.44': + resolution: {integrity: sha512-sDaBIT0yrNNIPfvlsiTCmANm07zKju+ipWODjEXgZlsjMeIJR3LVp7RDyAOzUoAsTbDfYKDWp+i5WrFiQP6rmQ==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/credential-provider-process@3.972.39': + resolution: {integrity: sha512-2k/amBifLd75eXNwgvPw/2lKYSQ3NhvHQgkVKVjfUq13/eJ3JRtHmznuFenn74OK3sSfp4SMy1YB2w+UVXoKqA==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/credential-provider-sso@3.972.43': + resolution: {integrity: sha512-LPc3+Y4vhH1T4x6CMqwCM6hk5+SRf/Lwmgm8INm95wxTtIRHcMwQUVkDzWu4Iw/RSncxYM2BC01OrYbxOPZvyg==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/credential-provider-web-identity@3.972.43': + resolution: {integrity: sha512-wQtL34lUD/09VXjwAUo2T+I3aEXRDxMB3DKmTJL/Zj0Gi6sLDTrVhae1XVt01yzkquOWajI/sZW72JGDZ1ciTw==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/eventstream-handler-node@3.972.17': + resolution: {integrity: sha512-WFwdNcjchKZr7jKYgGimUZO8sSKQF/le7GGqgeCzz/lHozInE6b0gFJ1YMr8NaIeAoWJwgtrF7RE4/qMgosAdQ==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/middleware-eventstream@3.972.13': + resolution: {integrity: sha512-ECfsw7mf6G/sxNbKbGE3/h1xeIArY/yRI1IjDGYkLgDIankh+aDOtDRSr40LVlIHGL9+jEH1cVuxmbJ8NLL/1A==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/middleware-websocket@3.972.21': + resolution: {integrity: sha512-yr+5+C7v9R55sAJ89A55Wrm7wIKPVn5cm6J3Hztnd5s/iwEUKxyJqCnIxJu4fVXgG9XBQD1Jc4rsWC1ozahJjA==} + engines: {node: '>= 14.0.0'} + + '@aws-sdk/nested-clients@3.997.11': + resolution: {integrity: sha512-nWXXJ1r/r8N2Gw1pWolRgED38/A9A8DHR2ETWIv220zh4PZHcybbR4hUVWWktmNXTRHzDJwRluapHn0rZxuoqA==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/signature-v4-multi-region@3.996.28': + resolution: {integrity: sha512-qs9z5LqXO/CZC2Lg9SGKpoLU8Rhi+m2pFKZqfO9pytX1clc0katqtsDNupJxFy0xT9wsZSPzM2v1y+/H/zfp5Q==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/token-providers@3.1048.0': + resolution: {integrity: sha512-k0y/GcuesuSfWyUM0WamrGyeZmltRYaPbHO82UDA6mZ/doB+FOHKutikPAtSXMn/hDz970cF+iRuuiYO9VEbAA==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/token-providers@3.1052.0': + resolution: {integrity: sha512-QqZNB3so7UIDxZtroc85TQaLVxdZRFm0eWM1CSR2N+b06as9TOrilvrlTZuj3guYlxMs6yLOgGxnklJ5qMYtTw==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/types@3.936.0': + resolution: {integrity: sha512-uz0/VlMd2pP5MepdrHizd+T+OKfyK4r3OA9JI+L/lPKg0YFQosdJNCKisr6o70E3dh8iMpFYxF1UN/4uZsyARg==} + engines: {node: '>=18.0.0'} + + '@aws-sdk/types@3.973.9': + resolution: {integrity: sha512-kuBfgQVdcz5Bmapc4A13YbpVw/pXkesfhetcFYwbntqas8sF41OHyd4o28+/TG2ZQdHBsv90Lsu5y6oitvYCdg==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/util-locate-window@3.965.5': + resolution: {integrity: sha512-WhlJNNINQB+9qtLtZJcpQdgZw3SCDCpXdUJP7cToGwHbCWCnRckGlc6Bx/OhWwIYFNAn+FIydY8SZ0QmVu3xTQ==} + engines: {node: '>=20.0.0'} + + '@aws-sdk/xml-builder@3.972.25': + resolution: {integrity: sha512-GH+Kjz4nPKWKHnsiQpnhP1MJdTGIcK4rAka6tzakgjjUkVgNsmPeEbbRAf09SzS1hjGu6duGHCBsxYke0BhHjQ==} + engines: {node: '>=20.0.0'} + + '@aws/lambda-invoke-store@0.2.4': + resolution: {integrity: sha512-iY8yvjE0y651BixKNPgmv1WrQc+GZ142sb0z4gYnChDDY2YqI4P/jsSopBWrKfAt7LOJAkOXt7rC/hms+WclQQ==} + engines: {node: '>=18.0.0'} + + '@babel/runtime@7.28.6': + resolution: {integrity: sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==} + engines: {node: '>=6.9.0'} + + '@changesets/apply-release-plan@7.0.14': + resolution: {integrity: sha512-ddBvf9PHdy2YY0OUiEl3TV78mH9sckndJR14QAt87KLEbIov81XO0q0QAmvooBxXlqRRP8I9B7XOzZwQG7JkWA==} + + '@changesets/assemble-release-plan@6.0.9': + resolution: {integrity: sha512-tPgeeqCHIwNo8sypKlS3gOPmsS3wP0zHt67JDuL20P4QcXiw/O4Hl7oXiuLnP9yg+rXLQ2sScdV1Kkzde61iSQ==} + + '@changesets/changelog-git@0.2.1': + resolution: {integrity: sha512-x/xEleCFLH28c3bQeQIyeZf8lFXyDFVn1SgcBiR2Tw/r4IAWlk1fzxCEZ6NxQAjF2Nwtczoen3OA2qR+UawQ8Q==} + + '@changesets/cli@2.29.8': + resolution: {integrity: sha512-1weuGZpP63YWUYjay/E84qqwcnt5yJMM0tep10Up7Q5cS/DGe2IZ0Uj3HNMxGhCINZuR7aO9WBMdKnPit5ZDPA==} + hasBin: true + + '@changesets/config@3.1.2': + resolution: {integrity: sha512-CYiRhA4bWKemdYi/uwImjPxqWNpqGPNbEBdX1BdONALFIDK7MCUj6FPkzD+z9gJcvDFUQJn9aDVf4UG7OT6Kog==} + + '@changesets/errors@0.2.0': + resolution: {integrity: sha512-6BLOQUscTpZeGljvyQXlWOItQyU71kCdGz7Pi8H8zdw6BI0g3m43iL4xKUVPWtG+qrrL9DTjpdn8eYuCQSRpow==} + + '@changesets/get-dependents-graph@2.1.3': + resolution: {integrity: sha512-gphr+v0mv2I3Oxt19VdWRRUxq3sseyUpX9DaHpTUmLj92Y10AGy+XOtV+kbM6L/fDcpx7/ISDFK6T8A/P3lOdQ==} + + '@changesets/get-release-plan@4.0.14': + resolution: {integrity: sha512-yjZMHpUHgl4Xl5gRlolVuxDkm4HgSJqT93Ri1Uz8kGrQb+5iJ8dkXJ20M2j/Y4iV5QzS2c5SeTxVSKX+2eMI0g==} + + '@changesets/get-version-range-type@0.4.0': + resolution: {integrity: sha512-hwawtob9DryoGTpixy1D3ZXbGgJu1Rhr+ySH2PvTLHvkZuQ7sRT4oQwMh0hbqZH1weAooedEjRsbrWcGLCeyVQ==} + + '@changesets/git@3.0.4': + resolution: {integrity: sha512-BXANzRFkX+XcC1q/d27NKvlJ1yf7PSAgi8JG6dt8EfbHFHi4neau7mufcSca5zRhwOL8j9s6EqsxmT+s+/E6Sw==} + + '@changesets/logger@0.1.1': + resolution: {integrity: sha512-OQtR36ZlnuTxKqoW4Sv6x5YIhOmClRd5pWsjZsddYxpWs517R0HkyiefQPIytCVh4ZcC5x9XaG8KTdd5iRQUfg==} + + '@changesets/parse@0.4.2': + resolution: {integrity: sha512-Uo5MC5mfg4OM0jU3up66fmSn6/NE9INK+8/Vn/7sMVcdWg46zfbvvUSjD9EMonVqPi9fbrJH9SXHn48Tr1f2yA==} + + '@changesets/pre@2.0.2': + resolution: {integrity: sha512-HaL/gEyFVvkf9KFg6484wR9s0qjAXlZ8qWPDkTyKF6+zqjBe/I2mygg3MbpZ++hdi0ToqNUF8cjj7fBy0dg8Ug==} + + '@changesets/read@0.6.6': + resolution: {integrity: sha512-P5QaN9hJSQQKJShzzpBT13FzOSPyHbqdoIBUd2DJdgvnECCyO6LmAOWSV+O8se2TaZJVwSXjL+v9yhb+a9JeJg==} + + '@changesets/should-skip-package@0.1.2': + resolution: {integrity: sha512-qAK/WrqWLNCP22UDdBTMPH5f41elVDlsNyat180A33dWxuUDyNpg6fPi/FyTZwRriVjg0L8gnjJn2F9XAoF0qw==} + + '@changesets/types@4.1.0': + resolution: {integrity: sha512-LDQvVDv5Kb50ny2s25Fhm3d9QSZimsoUGBsUioj6MC3qbMUCuC8GPIvk/M6IvXx3lYhAs0lwWUQLb+VIEUCECw==} + + '@changesets/types@6.1.0': + resolution: {integrity: sha512-rKQcJ+o1nKNgeoYRHKOS07tAMNd3YSN0uHaJOZYjBAgxfV7TUE7JE+z4BzZdQwb5hKaYbayKN5KrYV7ODb2rAA==} + + '@changesets/write@0.4.0': + resolution: {integrity: sha512-CdTLvIOPiCNuH71pyDu3rA+Q0n65cmAbXnwWH84rKGiFumFzkmHNT8KHTMEchcxN+Kl8I54xGUhJ7l3E7X396Q==} + + '@earendil-works/pi-agent-core@0.78.0': + resolution: {integrity: sha512-xhWd59Qzd8yO88gYQw2S4dEQstJJEiUtxRP01//YzVJ61jCtUASMfcyAmYhgGYR4Onp7GmwEAbBBGOiV6Iwk9g==} + engines: {node: '>=22.19.0'} + + '@earendil-works/pi-ai@0.78.0': + resolution: {integrity: sha512-q0hUrvT6ngT6cgBX0oIbzfQfmzztgdkZobP8OTL+sCOOBlnG6+1YRt8g7zO9CC/4NdeYEqa7uGqWdQhH0fjCLA==} + engines: {node: '>=22.19.0'} + hasBin: true + + '@earendil-works/pi-coding-agent@0.78.0': + resolution: {integrity: sha512-gXt6pD3BoSG0yLwfLqb6844vz6qAO87PvNrv+YSDYKP3QliTjcwIld9v4ihmDcmBjO13QwKswubq/lYCvn4bkg==} + engines: {node: '>=22.19.0'} + hasBin: true + + '@earendil-works/pi-tui@0.78.0': + resolution: {integrity: sha512-3a705FnsVVUhAyceShNB3kS2rpxcxLcx+hqB0u6MMMpHwQGbW+m++MqA6r7eOzq/8FLx5e3vDh38h/SVTk2qzw==} + engines: {node: '>=22.19.0'} + + '@esbuild/aix-ppc64@0.25.12': + resolution: {integrity: sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [aix] + + '@esbuild/aix-ppc64@0.27.0': + resolution: {integrity: sha512-KuZrd2hRjz01y5JK9mEBSD3Vj3mbCvemhT466rSuJYeE/hjuBrHfjjcjMdTm/sz7au+++sdbJZJmuBwQLuw68A==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [aix] + + '@esbuild/android-arm64@0.25.12': + resolution: {integrity: sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [android] + + '@esbuild/android-arm64@0.27.0': + resolution: {integrity: sha512-CC3vt4+1xZrs97/PKDkl0yN7w8edvU2vZvAFGD16n9F0Cvniy5qvzRXjfO1l94efczkkQE6g1x0i73Qf5uthOQ==} + engines: {node: '>=18'} + cpu: [arm64] + os: [android] + + '@esbuild/android-arm@0.25.12': + resolution: {integrity: sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==} + engines: {node: '>=18'} + cpu: [arm] + os: [android] + + '@esbuild/android-arm@0.27.0': + resolution: {integrity: sha512-j67aezrPNYWJEOHUNLPj9maeJte7uSMM6gMoxfPC9hOg8N02JuQi/T7ewumf4tNvJadFkvLZMlAq73b9uwdMyQ==} + engines: {node: '>=18'} + cpu: [arm] + os: [android] + + '@esbuild/android-x64@0.25.12': + resolution: {integrity: sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==} + engines: {node: '>=18'} + cpu: [x64] + os: [android] + + '@esbuild/android-x64@0.27.0': + resolution: {integrity: sha512-wurMkF1nmQajBO1+0CJmcN17U4BP6GqNSROP8t0X/Jiw2ltYGLHpEksp9MpoBqkrFR3kv2/te6Sha26k3+yZ9Q==} + engines: {node: '>=18'} + cpu: [x64] + os: [android] + + '@esbuild/darwin-arm64@0.25.12': + resolution: {integrity: sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [darwin] + + '@esbuild/darwin-arm64@0.27.0': + resolution: {integrity: sha512-uJOQKYCcHhg07DL7i8MzjvS2LaP7W7Pn/7uA0B5S1EnqAirJtbyw4yC5jQ5qcFjHK9l6o/MX9QisBg12kNkdHg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [darwin] + + '@esbuild/darwin-x64@0.25.12': + resolution: {integrity: sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==} + engines: {node: '>=18'} + cpu: [x64] + os: [darwin] + + '@esbuild/darwin-x64@0.27.0': + resolution: {integrity: sha512-8mG6arH3yB/4ZXiEnXof5MK72dE6zM9cDvUcPtxhUZsDjESl9JipZYW60C3JGreKCEP+p8P/72r69m4AZGJd5g==} + engines: {node: '>=18'} + cpu: [x64] + os: [darwin] + + '@esbuild/freebsd-arm64@0.25.12': + resolution: {integrity: sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [freebsd] + + '@esbuild/freebsd-arm64@0.27.0': + resolution: {integrity: sha512-9FHtyO988CwNMMOE3YIeci+UV+x5Zy8fI2qHNpsEtSF83YPBmE8UWmfYAQg6Ux7Gsmd4FejZqnEUZCMGaNQHQw==} + engines: {node: '>=18'} + cpu: [arm64] + os: [freebsd] + + '@esbuild/freebsd-x64@0.25.12': + resolution: {integrity: sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==} + engines: {node: '>=18'} + cpu: [x64] + os: [freebsd] + + '@esbuild/freebsd-x64@0.27.0': + resolution: {integrity: sha512-zCMeMXI4HS/tXvJz8vWGexpZj2YVtRAihHLk1imZj4efx1BQzN76YFeKqlDr3bUWI26wHwLWPd3rwh6pe4EV7g==} + engines: {node: '>=18'} + cpu: [x64] + os: [freebsd] + + '@esbuild/linux-arm64@0.25.12': + resolution: {integrity: sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==} + engines: {node: '>=18'} + cpu: [arm64] + os: [linux] + + '@esbuild/linux-arm64@0.27.0': + resolution: {integrity: sha512-AS18v0V+vZiLJyi/4LphvBE+OIX682Pu7ZYNsdUHyUKSoRwdnOsMf6FDekwoAFKej14WAkOef3zAORJgAtXnlQ==} + engines: {node: '>=18'} + cpu: [arm64] + os: [linux] + + '@esbuild/linux-arm@0.25.12': + resolution: {integrity: sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==} + engines: {node: '>=18'} + cpu: [arm] + os: [linux] + + '@esbuild/linux-arm@0.27.0': + resolution: {integrity: sha512-t76XLQDpxgmq2cNXKTVEB7O7YMb42atj2Re2Haf45HkaUpjM2J0UuJZDuaGbPbamzZ7bawyGFUkodL+zcE+jvQ==} + engines: {node: '>=18'} + cpu: [arm] + os: [linux] + + '@esbuild/linux-ia32@0.25.12': + resolution: {integrity: sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==} + engines: {node: '>=18'} + cpu: [ia32] + os: [linux] + + '@esbuild/linux-ia32@0.27.0': + resolution: {integrity: sha512-Mz1jxqm/kfgKkc/KLHC5qIujMvnnarD9ra1cEcrs7qshTUSksPihGrWHVG5+osAIQ68577Zpww7SGapmzSt4Nw==} + engines: {node: '>=18'} + cpu: [ia32] + os: [linux] + + '@esbuild/linux-loong64@0.25.12': + resolution: {integrity: sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==} + engines: {node: '>=18'} + cpu: [loong64] + os: [linux] + + '@esbuild/linux-loong64@0.27.0': + resolution: {integrity: sha512-QbEREjdJeIreIAbdG2hLU1yXm1uu+LTdzoq1KCo4G4pFOLlvIspBm36QrQOar9LFduavoWX2msNFAAAY9j4BDg==} + engines: {node: '>=18'} + cpu: [loong64] + os: [linux] + + '@esbuild/linux-mips64el@0.25.12': + resolution: {integrity: sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==} + engines: {node: '>=18'} + cpu: [mips64el] + os: [linux] + + '@esbuild/linux-mips64el@0.27.0': + resolution: {integrity: sha512-sJz3zRNe4tO2wxvDpH/HYJilb6+2YJxo/ZNbVdtFiKDufzWq4JmKAiHy9iGoLjAV7r/W32VgaHGkk35cUXlNOg==} + engines: {node: '>=18'} + cpu: [mips64el] + os: [linux] + + '@esbuild/linux-ppc64@0.25.12': + resolution: {integrity: sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [linux] + + '@esbuild/linux-ppc64@0.27.0': + resolution: {integrity: sha512-z9N10FBD0DCS2dmSABDBb5TLAyF1/ydVb+N4pi88T45efQ/w4ohr/F/QYCkxDPnkhkp6AIpIcQKQ8F0ANoA2JA==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [linux] + + '@esbuild/linux-riscv64@0.25.12': + resolution: {integrity: sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==} + engines: {node: '>=18'} + cpu: [riscv64] + os: [linux] + + '@esbuild/linux-riscv64@0.27.0': + resolution: {integrity: sha512-pQdyAIZ0BWIC5GyvVFn5awDiO14TkT/19FTmFcPdDec94KJ1uZcmFs21Fo8auMXzD4Tt+diXu1LW1gHus9fhFQ==} + engines: {node: '>=18'} + cpu: [riscv64] + os: [linux] + + '@esbuild/linux-s390x@0.25.12': + resolution: {integrity: sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==} + engines: {node: '>=18'} + cpu: [s390x] + os: [linux] + + '@esbuild/linux-s390x@0.27.0': + resolution: {integrity: sha512-hPlRWR4eIDDEci953RI1BLZitgi5uqcsjKMxwYfmi4LcwyWo2IcRP+lThVnKjNtk90pLS8nKdroXYOqW+QQH+w==} + engines: {node: '>=18'} + cpu: [s390x] + os: [linux] + + '@esbuild/linux-x64@0.25.12': + resolution: {integrity: sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==} + engines: {node: '>=18'} + cpu: [x64] + os: [linux] + + '@esbuild/linux-x64@0.27.0': + resolution: {integrity: sha512-1hBWx4OUJE2cab++aVZ7pObD6s+DK4mPGpemtnAORBvb5l/g5xFGk0vc0PjSkrDs0XaXj9yyob3d14XqvnQ4gw==} + engines: {node: '>=18'} + cpu: [x64] + os: [linux] + + '@esbuild/netbsd-arm64@0.25.12': + resolution: {integrity: sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [netbsd] + + '@esbuild/netbsd-arm64@0.27.0': + resolution: {integrity: sha512-6m0sfQfxfQfy1qRuecMkJlf1cIzTOgyaeXaiVaaki8/v+WB+U4hc6ik15ZW6TAllRlg/WuQXxWj1jx6C+dfy3w==} + engines: {node: '>=18'} + cpu: [arm64] + os: [netbsd] + + '@esbuild/netbsd-x64@0.25.12': + resolution: {integrity: sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==} + engines: {node: '>=18'} + cpu: [x64] + os: [netbsd] + + '@esbuild/netbsd-x64@0.27.0': + resolution: {integrity: sha512-xbbOdfn06FtcJ9d0ShxxvSn2iUsGd/lgPIO2V3VZIPDbEaIj1/3nBBe1AwuEZKXVXkMmpr6LUAgMkLD/4D2PPA==} + engines: {node: '>=18'} + cpu: [x64] + os: [netbsd] + + '@esbuild/openbsd-arm64@0.25.12': + resolution: {integrity: sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openbsd] + + '@esbuild/openbsd-arm64@0.27.0': + resolution: {integrity: sha512-fWgqR8uNbCQ/GGv0yhzttj6sU/9Z5/Sv/VGU3F5OuXK6J6SlriONKrQ7tNlwBrJZXRYk5jUhuWvF7GYzGguBZQ==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openbsd] + + '@esbuild/openbsd-x64@0.25.12': + resolution: {integrity: sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==} + engines: {node: '>=18'} + cpu: [x64] + os: [openbsd] + + '@esbuild/openbsd-x64@0.27.0': + resolution: {integrity: sha512-aCwlRdSNMNxkGGqQajMUza6uXzR/U0dIl1QmLjPtRbLOx3Gy3otfFu/VjATy4yQzo9yFDGTxYDo1FfAD9oRD2A==} + engines: {node: '>=18'} + cpu: [x64] + os: [openbsd] + + '@esbuild/openharmony-arm64@0.25.12': + resolution: {integrity: sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openharmony] + + '@esbuild/openharmony-arm64@0.27.0': + resolution: {integrity: sha512-nyvsBccxNAsNYz2jVFYwEGuRRomqZ149A39SHWk4hV0jWxKM0hjBPm3AmdxcbHiFLbBSwG6SbpIcUbXjgyECfA==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openharmony] + + '@esbuild/sunos-x64@0.25.12': + resolution: {integrity: sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==} + engines: {node: '>=18'} + cpu: [x64] + os: [sunos] + + '@esbuild/sunos-x64@0.27.0': + resolution: {integrity: sha512-Q1KY1iJafM+UX6CFEL+F4HRTgygmEW568YMqDA5UV97AuZSm21b7SXIrRJDwXWPzr8MGr75fUZPV67FdtMHlHA==} + engines: {node: '>=18'} + cpu: [x64] + os: [sunos] + + '@esbuild/win32-arm64@0.25.12': + resolution: {integrity: sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [win32] + + '@esbuild/win32-arm64@0.27.0': + resolution: {integrity: sha512-W1eyGNi6d+8kOmZIwi/EDjrL9nxQIQ0MiGqe/AWc6+IaHloxHSGoeRgDRKHFISThLmsewZ5nHFvGFWdBYlgKPg==} + engines: {node: '>=18'} + cpu: [arm64] + os: [win32] + + '@esbuild/win32-ia32@0.25.12': + resolution: {integrity: sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==} + engines: {node: '>=18'} + cpu: [ia32] + os: [win32] + + '@esbuild/win32-ia32@0.27.0': + resolution: {integrity: sha512-30z1aKL9h22kQhilnYkORFYt+3wp7yZsHWus+wSKAJR8JtdfI76LJ4SBdMsCopTR3z/ORqVu5L1vtnHZWVj4cQ==} + engines: {node: '>=18'} + cpu: [ia32] + os: [win32] + + '@esbuild/win32-x64@0.25.12': + resolution: {integrity: sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==} + engines: {node: '>=18'} + cpu: [x64] + os: [win32] + + '@esbuild/win32-x64@0.27.0': + resolution: {integrity: sha512-aIitBcjQeyOhMTImhLZmtxfdOcuNRpwlPNmlFKPcHQYPhEssw75Cl1TSXJXpMkzaua9FUetx/4OQKq7eJul5Cg==} + engines: {node: '>=18'} + cpu: [x64] + os: [win32] + + '@eslint-community/eslint-utils@4.9.0': + resolution: {integrity: sha512-ayVFHdtZ+hsq1t2Dy24wCmGXGe4q9Gu3smhLYALJrr473ZH27MsnSL+LKUlimp4BWJqMDMLmPpx/Q9R3OAlL4g==} + engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0} + peerDependencies: + eslint: ^6.0.0 || ^7.0.0 || >=8.0.0 + + '@eslint-community/regexpp@4.12.2': + resolution: {integrity: sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==} + engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0} + + '@eslint/config-array@0.21.2': + resolution: {integrity: sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@eslint/config-helpers@0.4.2': + resolution: {integrity: sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@eslint/core@0.17.0': + resolution: {integrity: sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@eslint/eslintrc@3.3.5': + resolution: {integrity: sha512-4IlJx0X0qftVsN5E+/vGujTRIFtwuLbNsVUe7TO6zYPDR1O6nFwvwhIKEKSrl6dZchmYBITazxKoUYOjdtjlRg==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@eslint/js@9.39.4': + resolution: {integrity: sha512-nE7DEIchvtiFTwBw4Lfbu59PG+kCofhjsKaCWzxTpt4lfRjRMqG6uMBzKXuEcyXhOHoUp9riAm7/aWYGhXZ9cw==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@eslint/object-schema@2.1.7': + resolution: {integrity: sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@eslint/plugin-kit@0.4.1': + resolution: {integrity: sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@google/genai@1.52.0': + resolution: {integrity: sha512-gwSvbpiN/17O9TbsqSsE/OzZcpv5Fo4RQjdngGgogtuB9RsyJ8ZHhX5KjHj1bp5N9snN2eK8LDGXSaWW2hof8Q==} + engines: {node: '>=20.0.0'} + peerDependencies: + '@modelcontextprotocol/sdk': ^1.25.2 + peerDependenciesMeta: + '@modelcontextprotocol/sdk': + optional: true + + '@hono/node-server@1.19.14': + resolution: {integrity: sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==} + engines: {node: '>=18.14.1'} + peerDependencies: + hono: ^4 + + '@humanfs/core@0.19.1': + resolution: {integrity: sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA==} + engines: {node: '>=18.18.0'} + + '@humanfs/node@0.16.7': + resolution: {integrity: sha512-/zUx+yOsIrG4Y43Eh2peDeKCxlRt/gET6aHfaKpuq267qXdYDFViVHfMaLyygZOnl0kGWxFIgsBy8QFuTLUXEQ==} + engines: {node: '>=18.18.0'} + + '@humanwhocodes/module-importer@1.0.1': + resolution: {integrity: sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==} + engines: {node: '>=12.22'} + + '@humanwhocodes/retry@0.4.3': + resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==} + engines: {node: '>=18.18'} + + '@inquirer/ansi@2.0.3': + resolution: {integrity: sha512-g44zhR3NIKVs0zUesa4iMzExmZpLUdTLRMCStqX3GE5NT6VkPcxQGJ+uC8tDgBUC/vB1rUhUd55cOf++4NZcmw==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + + '@inquirer/checkbox@5.0.4': + resolution: {integrity: sha512-DrAMU3YBGMUAp6ArwTIp/25CNDtDbxk7UjIrrtM25JVVrlVYlVzHh5HR1BDFu9JMyUoZ4ZanzeaHqNDttf3gVg==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/confirm@6.0.4': + resolution: {integrity: sha512-WdaPe7foUnoGYvXzH4jp4wH/3l+dBhZ3uwhKjXjwdrq5tEIFaANxj6zrGHxLdsIA0yKM0kFPVcEalOZXBB5ISA==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/core@11.1.1': + resolution: {integrity: sha512-hV9o15UxX46OyQAtaoMqAOxGR8RVl1aZtDx1jHbCtSJy1tBdTfKxLPKf7utsE4cRy4tcmCQ4+vdV+ca+oNxqNA==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/editor@5.0.4': + resolution: {integrity: sha512-QI3Jfqcv6UO2/VJaEFONH8Im1ll++Xn/AJTBn9Xf+qx2M+H8KZAdQ5sAe2vtYlo+mLW+d7JaMJB4qWtK4BG3pw==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/expand@5.0.4': + resolution: {integrity: sha512-0I/16YwPPP0Co7a5MsomlZLpch48NzYfToyqYAOWtBmaXSB80RiNQ1J+0xx2eG+Wfxt0nHtpEWSRr6CzNVnOGg==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/external-editor@1.0.3': + resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==} + engines: {node: '>=18'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/external-editor@2.0.3': + resolution: {integrity: sha512-LgyI7Agbda74/cL5MvA88iDpvdXI2KuMBCGRkbCl2Dg1vzHeOgs+s0SDcXV7b+WZJrv2+ERpWSM65Fpi9VfY3w==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/figures@2.0.3': + resolution: {integrity: sha512-y09iGt3JKoOCBQ3w4YrSJdokcD8ciSlMIWsD+auPu+OZpfxLuyz+gICAQ6GCBOmJJt4KEQGHuZSVff2jiNOy7g==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + + '@inquirer/input@5.0.4': + resolution: {integrity: sha512-4B3s3jvTREDFvXWit92Yc6jF1RJMDy2VpSqKtm4We2oVU65YOh2szY5/G14h4fHlyQdpUmazU5MPCFZPRJ0AOw==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/number@4.0.4': + resolution: {integrity: sha512-CmMp9LF5HwE+G/xWsC333TlCzYYbXMkcADkKzcawh49fg2a1ryLc7JL1NJYYt1lJ+8f4slikNjJM9TEL/AljYQ==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/password@5.0.4': + resolution: {integrity: sha512-ZCEPyVYvHK4W4p2Gy6sTp9nqsdHQCfiPXIP9LbJVW4yCinnxL/dDDmPaEZVysGrj8vxVReRnpfS2fOeODe9zjg==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/prompts@8.2.0': + resolution: {integrity: sha512-rqTzOprAj55a27jctS3vhvDDJzYXsr33WXTjODgVOru21NvBo9yIgLIAf7SBdSV0WERVly3dR6TWyp7ZHkvKFA==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/rawlist@5.2.0': + resolution: {integrity: sha512-CciqGoOUMrFo6HxvOtU5uL8fkjCmzyeB6fG7O1vdVAZVSopUBYECOwevDBlqNLyyYmzpm2Gsn/7nLrpruy9RFg==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/search@4.1.0': + resolution: {integrity: sha512-EAzemfiP4IFvIuWnrHpgZs9lAhWDA0GM3l9F4t4mTQ22IFtzfrk8xbkMLcAN7gmVML9O/i+Hzu8yOUyAaL6BKA==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/select@5.0.4': + resolution: {integrity: sha512-s8KoGpPYMEQ6WXc0dT9blX2NtIulMdLOO3LA1UKOiv7KFWzlJ6eLkEYTDBIi+JkyKXyn8t/CD6TinxGjyLt57g==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@inquirer/type@4.0.3': + resolution: {integrity: sha512-cKZN7qcXOpj1h+1eTTcGDVLaBIHNMT1Rz9JqJP5MnEJ0JhgVWllx7H/tahUp5YEK1qaByH2Itb8wLG/iScD5kw==} + engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'} + peerDependencies: + '@types/node': '>=18' + peerDependenciesMeta: + '@types/node': + optional: true + + '@jridgewell/gen-mapping@0.3.13': + resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==} + + '@jridgewell/resolve-uri@3.1.2': + resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==} + engines: {node: '>=6.0.0'} + + '@jridgewell/sourcemap-codec@1.5.5': + resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==} + + '@jridgewell/trace-mapping@0.3.31': + resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==} + + '@manypkg/find-root@1.1.0': + resolution: {integrity: sha512-mki5uBvhHzO8kYYix/WRy2WX8S3B5wdVSc9D6KcU5lQNglP2yt58/VfLuAK49glRXChosY8ap2oJ1qgma3GUVA==} + + '@manypkg/get-packages@1.1.3': + resolution: {integrity: sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==} + + '@mariozechner/clipboard-darwin-arm64@0.3.9': + resolution: {integrity: sha512-BfgV7vCEWZwJwZJw03r6bP5+tf0iI/ANuQYCxi9RNn7FrWB3yzGuMKCrNLRl6V761vXRdL8+OqZ0wd4TqlsNOQ==} + engines: {node: '>= 10'} + cpu: [arm64] + os: [darwin] + + '@mariozechner/clipboard-darwin-universal@0.3.9': + resolution: {integrity: sha512-BGGR4iA9Z2shAjI65eI5xtyb3LYNlDW9X3gxKxDbqtbnREohsrqznov6zpKoIrsRWpzlYVEdKphS7ksJ0/ndSQ==} + engines: {node: '>= 10'} + os: [darwin] + + '@mariozechner/clipboard-darwin-x64@0.3.9': + resolution: {integrity: sha512-4kURmCbS6nt8uYhtmWpUcJWyPHfmAr5dTpXD1nO3pIfa+TSQ9DbrGOYCKH+aEFW47XhQ4Vp8ZTszie+wfFvDKg==} + engines: {node: '>= 10'} + cpu: [x64] + os: [darwin] + + '@mariozechner/clipboard-linux-arm64-gnu@0.3.9': + resolution: {integrity: sha512-g59OkUGP2DDfCOIKypHeYgv2M55u/cKvXa5dSxFbEJ34XvIQMdcVmpKCkGUro3ZgefXiGVdwguvTMQGpHWzIXw==} + engines: {node: '>= 10'} + cpu: [arm64] + os: [linux] + libc: [glibc] + + '@mariozechner/clipboard-linux-arm64-musl@0.3.9': + resolution: {integrity: sha512-AGuJdgKsmJdm4Pych7kv3sqe591ERRaAHW3xjLooiFzn8J+PxUyof++7YZrB5Y5tpnTO+K18Og3taj2NpluCRQ==} + engines: {node: '>= 10'} + cpu: [arm64] + os: [linux] + libc: [musl] + + '@mariozechner/clipboard-linux-riscv64-gnu@0.3.9': + resolution: {integrity: sha512-DXBEAiuMpk7dhS1a9NzNxVAFi1vaKoPu7rQNgY8LIDLGrK3lnIp3nT10DUum+PKVJoJppIP+NAA8IZe4DMNDPw==} + engines: {node: '>= 10'} + cpu: [riscv64] + os: [linux] + libc: [glibc] + + '@mariozechner/clipboard-linux-x64-gnu@0.3.9': + resolution: {integrity: sha512-WORrMLd6EpElEME7JRKfSaY34nW1P5LbdgK5YNCS1ncG2LqmITsSMEJ8nh2mpvxb3TxqbOOKgY7k9eMJYlW9Mw==} + engines: {node: '>= 10'} + cpu: [x64] + os: [linux] + libc: [glibc] + + '@mariozechner/clipboard-linux-x64-musl@0.3.9': + resolution: {integrity: sha512-/DHn+1DrfL6oRaPPWXaOKvonFFrni666fxd+zFqiQEfvBH0tsHVWjq9iqBk0oDp0qaPA72lIMy5BptxISBEhZQ==} + engines: {node: '>= 10'} + cpu: [x64] + os: [linux] + libc: [musl] + + '@mariozechner/clipboard-win32-arm64-msvc@0.3.9': + resolution: {integrity: sha512-O5FHD3ErkMwMhNzAfu3ggy0ug4z7btZuoQgwwxlzPrwV2bxlD6WDpqBY4NCgICAgZdDKdp+loUEKVAVt8aYnhQ==} + engines: {node: '>= 10'} + cpu: [arm64] + os: [win32] + + '@mariozechner/clipboard-win32-x64-msvc@0.3.9': + resolution: {integrity: sha512-ihQC3EufqEY81vhXBgVBtK4prL+wc62zJsSvxrgz7K1hsdt6OObz6v9p3Rn1OG3GJksTTKMJF0u/guMISHPhSA==} + engines: {node: '>= 10'} + cpu: [x64] + os: [win32] + + '@mariozechner/clipboard@0.3.9': + resolution: {integrity: sha512-ABnA53mdfkGZwOFUdZNv2S0CWGO/EIuPj8Vv9xmBFmSYg/qFc7ihO6q5FcQjvoE67kZpWkEc4AhD6B/os04yuA==} + engines: {node: '>= 10'} + + '@mistralai/mistralai@2.2.1': + resolution: {integrity: sha512-uKU8CZmL2RzYKmplsU01hii4p3pe4HqJefpWNRWXm1Tcm0Sm4xXfwSLIy4k7ZCPlbETCGcp69E7hZs+WOJ5itQ==} + + '@modelcontextprotocol/sdk@1.29.0': + resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==} + engines: {node: '>=18'} + peerDependencies: + '@cfworker/json-schema': ^4.1.1 + zod: ^3.25 || ^4.0 + peerDependenciesMeta: + '@cfworker/json-schema': + optional: true + + '@nodable/entities@2.1.0': + resolution: {integrity: sha512-nyT7T3nbMyBI/lvr6L5TyWbFJAI9FTgVRakNoBqCD+PmID8DzFrrNdLLtHMwMszOtqZa8PAOV24ZqDnQrhQINA==} + + '@nodelib/fs.scandir@2.1.5': + resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==} + engines: {node: '>= 8'} + + '@nodelib/fs.stat@2.0.5': + resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==} + engines: {node: '>= 8'} + + '@nodelib/fs.walk@1.2.8': + resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==} + engines: {node: '>= 8'} + + '@opentelemetry/api@1.9.0': + resolution: {integrity: sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==} + engines: {node: '>=8.0.0'} + + '@pkgr/core@0.3.6': + resolution: {integrity: sha512-SEeaJLb3qBNF/OaXnaR1NmmBbFYk1zC0ZH/52fATcRPLFg/p791YrcyFFy44Bo9sLaGuSuLp5Q6axbb/O+v/RA==} + engines: {node: ^14.18.0 || >=16.0.0} + + '@protobufjs/aspromise@1.1.2': + resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==} + + '@protobufjs/base64@1.1.2': + resolution: {integrity: sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==} + + '@protobufjs/codegen@2.0.5': + resolution: {integrity: sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==} + + '@protobufjs/eventemitter@1.1.1': + resolution: {integrity: sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==} + + '@protobufjs/fetch@1.1.1': + resolution: {integrity: sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==} + + '@protobufjs/float@1.0.2': + resolution: {integrity: sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==} + + '@protobufjs/inquire@1.1.2': + resolution: {integrity: sha512-pa0vFRuws4wkvaXKK1uXZMAwAX4/t8ANaJo45iw/oQHNQ9q5xUzwgFmVJGXiga2BeN+zpX7Vf9vmsiIa2J+MUw==} + + '@protobufjs/path@1.1.2': + resolution: {integrity: sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==} + + '@protobufjs/pool@1.1.0': + resolution: {integrity: sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==} + + '@protobufjs/utf8@1.1.1': + resolution: {integrity: sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==} + + '@rollup/rollup-android-arm-eabi@4.53.3': + resolution: {integrity: sha512-mRSi+4cBjrRLoaal2PnqH82Wqyb+d3HsPUN/W+WslCXsZsyHa9ZeQQX/pQsZaVIWDkPcpV6jJ+3KLbTbgnwv8w==} + cpu: [arm] + os: [android] + + '@rollup/rollup-android-arm64@4.53.3': + resolution: {integrity: sha512-CbDGaMpdE9sh7sCmTrTUyllhrg65t6SwhjlMJsLr+J8YjFuPmCEjbBSx4Z/e4SmDyH3aB5hGaJUP2ltV/vcs4w==} + cpu: [arm64] + os: [android] + + '@rollup/rollup-darwin-arm64@4.53.3': + resolution: {integrity: sha512-Nr7SlQeqIBpOV6BHHGZgYBuSdanCXuw09hon14MGOLGmXAFYjx1wNvquVPmpZnl0tLjg25dEdr4IQ6GgyToCUA==} + cpu: [arm64] + os: [darwin] + + '@rollup/rollup-darwin-x64@4.53.3': + resolution: {integrity: sha512-DZ8N4CSNfl965CmPktJ8oBnfYr3F8dTTNBQkRlffnUarJ2ohudQD17sZBa097J8xhQ26AwhHJ5mvUyQW8ddTsQ==} + cpu: [x64] + os: [darwin] + + '@rollup/rollup-freebsd-arm64@4.53.3': + resolution: {integrity: sha512-yMTrCrK92aGyi7GuDNtGn2sNW+Gdb4vErx4t3Gv/Tr+1zRb8ax4z8GWVRfr3Jw8zJWvpGHNpss3vVlbF58DZ4w==} + cpu: [arm64] + os: [freebsd] + + '@rollup/rollup-freebsd-x64@4.53.3': + resolution: {integrity: sha512-lMfF8X7QhdQzseM6XaX0vbno2m3hlyZFhwcndRMw8fbAGUGL3WFMBdK0hbUBIUYcEcMhVLr1SIamDeuLBnXS+Q==} + cpu: [x64] + os: [freebsd] + + '@rollup/rollup-linux-arm-gnueabihf@4.53.3': + resolution: {integrity: sha512-k9oD15soC/Ln6d2Wv/JOFPzZXIAIFLp6B+i14KhxAfnq76ajt0EhYc5YPeX6W1xJkAdItcVT+JhKl1QZh44/qw==} + cpu: [arm] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-arm-musleabihf@4.53.3': + resolution: {integrity: sha512-vTNlKq+N6CK/8UktsrFuc+/7NlEYVxgaEgRXVUVK258Z5ymho29skzW1sutgYjqNnquGwVUObAaxae8rZ6YMhg==} + cpu: [arm] + os: [linux] + libc: [musl] + + '@rollup/rollup-linux-arm64-gnu@4.53.3': + resolution: {integrity: sha512-RGrFLWgMhSxRs/EWJMIFM1O5Mzuz3Xy3/mnxJp/5cVhZ2XoCAxJnmNsEyeMJtpK+wu0FJFWz+QF4mjCA7AUQ3w==} + cpu: [arm64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-arm64-musl@4.53.3': + resolution: {integrity: sha512-kASyvfBEWYPEwe0Qv4nfu6pNkITLTb32p4yTgzFCocHnJLAHs+9LjUu9ONIhvfT/5lv4YS5muBHyuV84epBo/A==} + cpu: [arm64] + os: [linux] + libc: [musl] + + '@rollup/rollup-linux-loong64-gnu@4.53.3': + resolution: {integrity: sha512-JiuKcp2teLJwQ7vkJ95EwESWkNRFJD7TQgYmCnrPtlu50b4XvT5MOmurWNrCj3IFdyjBQ5p9vnrX4JM6I8OE7g==} + cpu: [loong64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-ppc64-gnu@4.53.3': + resolution: {integrity: sha512-EoGSa8nd6d3T7zLuqdojxC20oBfNT8nexBbB/rkxgKj5T5vhpAQKKnD+h3UkoMuTyXkP5jTjK/ccNRmQrPNDuw==} + cpu: [ppc64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-riscv64-gnu@4.53.3': + resolution: {integrity: sha512-4s+Wped2IHXHPnAEbIB0YWBv7SDohqxobiiPA1FIWZpX+w9o2i4LezzH/NkFUl8LRci/8udci6cLq+jJQlh+0g==} + cpu: [riscv64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-riscv64-musl@4.53.3': + resolution: {integrity: sha512-68k2g7+0vs2u9CxDt5ktXTngsxOQkSEV/xBbwlqYcUrAVh6P9EgMZvFsnHy4SEiUl46Xf0IObWVbMvPrr2gw8A==} + cpu: [riscv64] + os: [linux] + libc: [musl] + + '@rollup/rollup-linux-s390x-gnu@4.53.3': + resolution: {integrity: sha512-VYsFMpULAz87ZW6BVYw3I6sWesGpsP9OPcyKe8ofdg9LHxSbRMd7zrVrr5xi/3kMZtpWL/wC+UIJWJYVX5uTKg==} + cpu: [s390x] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-x64-gnu@4.53.3': + resolution: {integrity: sha512-3EhFi1FU6YL8HTUJZ51imGJWEX//ajQPfqWLI3BQq4TlvHy4X0MOr5q3D2Zof/ka0d5FNdPwZXm3Yyib/UEd+w==} + cpu: [x64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-x64-musl@4.53.3': + resolution: {integrity: sha512-eoROhjcc6HbZCJr+tvVT8X4fW3/5g/WkGvvmwz/88sDtSJzO7r/blvoBDgISDiCjDRZmHpwud7h+6Q9JxFwq1Q==} + cpu: [x64] + os: [linux] + libc: [musl] + + '@rollup/rollup-openharmony-arm64@4.53.3': + resolution: {integrity: sha512-OueLAWgrNSPGAdUdIjSWXw+u/02BRTcnfw9PN41D2vq/JSEPnJnVuBgw18VkN8wcd4fjUs+jFHVM4t9+kBSNLw==} + cpu: [arm64] + os: [openharmony] + + '@rollup/rollup-win32-arm64-msvc@4.53.3': + resolution: {integrity: sha512-GOFuKpsxR/whszbF/bzydebLiXIHSgsEUp6M0JI8dWvi+fFa1TD6YQa4aSZHtpmh2/uAlj/Dy+nmby3TJ3pkTw==} + cpu: [arm64] + os: [win32] + + '@rollup/rollup-win32-ia32-msvc@4.53.3': + resolution: {integrity: sha512-iah+THLcBJdpfZ1TstDFbKNznlzoxa8fmnFYK4V67HvmuNYkVdAywJSoteUszvBQ9/HqN2+9AZghbajMsFT+oA==} + cpu: [ia32] + os: [win32] + + '@rollup/rollup-win32-x64-gnu@4.53.3': + resolution: {integrity: sha512-J9QDiOIZlZLdcot5NXEepDkstocktoVjkaKUtqzgzpt2yWjGlbYiKyp05rWwk4nypbYUNoFAztEgixoLaSETkg==} + cpu: [x64] + os: [win32] + + '@rollup/rollup-win32-x64-msvc@4.53.3': + resolution: {integrity: sha512-UhTd8u31dXadv0MopwGgNOBpUVROFKWVQgAg5N1ESyCz8AuBcMqm4AuTjrwgQKGDfoFuz02EuMRHQIw/frmYKQ==} + cpu: [x64] + os: [win32] + + '@silvia-odwyer/photon-node@0.3.4': + resolution: {integrity: sha512-bnly4BKB3KDTFxrUIcgCLbaeVVS8lrAkri1pEzskpmxu9MdfGQTy8b8EgcD83ywD3RPMsIulY8xJH5Awa+t9fA==} + + '@smithy/core@3.24.4': + resolution: {integrity: sha512-3UNRKEyQyAgVgM0LGlerCLm+ChZWZ1GPfde+jBEW6bm6bSBGU1p0EbblaUV3unbhwvidjLA5Zs3sOs7mnZwvAw==} + engines: {node: '>=18.0.0'} + + '@smithy/credential-provider-imds@4.3.4': + resolution: {integrity: sha512-vKW0MEFRU4Y3MkVZUkpJm+g9qyPGLCXhc0YLggUdSdBB4g7IaSSsCE75P9rBXyWHrXY1UYSQUl8/DwsTR7QciA==} + engines: {node: '>=18.0.0'} + + '@smithy/eventstream-codec@4.2.5': + resolution: {integrity: sha512-Ogt4Zi9hEbIP17oQMd68qYOHUzmH47UkK7q7Gl55iIm9oKt27MUGrC5JfpMroeHjdkOliOA4Qt3NQ1xMq/nrlA==} + engines: {node: '>=18.0.0'} + + '@smithy/fetch-http-handler@5.4.4': + resolution: {integrity: sha512-qM7AUKI4G6d7lNgaZD3lA1tWSolh5r6gcixfTZAPstVURfjIbvreVTPz+994M0yC3HbX4YYhDRgr31Xy3XwWOQ==} + engines: {node: '>=18.0.0'} + + '@smithy/is-array-buffer@2.2.0': + resolution: {integrity: sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==} + engines: {node: '>=14.0.0'} + + '@smithy/is-array-buffer@4.2.0': + resolution: {integrity: sha512-DZZZBvC7sjcYh4MazJSGiWMI2L7E0oCiRHREDzIxi/M2LY79/21iXt6aPLHge82wi5LsuRF5A06Ds3+0mlh6CQ==} + engines: {node: '>=18.0.0'} + + '@smithy/node-http-handler@4.7.3': + resolution: {integrity: sha512-/jPhevcTFPMVl6KNjbaI47iOg1zxC7IsnX4PQDGVZKMFceOXtB8IEYaB7a9VvkP/3oC60WzTeKocvSI7vLT0vA==} + engines: {node: '>=18.0.0'} + + '@smithy/node-http-handler@4.7.4': + resolution: {integrity: sha512-HIeF+1vrDGzPkkv39Hj2vlHSXHY3p958jd/8ZnePIY6+ZOsQX8coyEUKO5yQu4r0bQIVsbpotVIrXXwyycMStQ==} + engines: {node: '>=18.0.0'} + + '@smithy/signature-v4@5.4.4': + resolution: {integrity: sha512-e5UtkMvsatzBfbeBZjEOt0k0Z3BEsjTFL/n6fdO5vtBLe67tdy0dX7xw2DU7uZ3acwoHyeCqpU2Fzb7pxwHb6Q==} + engines: {node: '>=18.0.0'} + + '@smithy/types@4.14.2': + resolution: {integrity: sha512-P+otAxbV4CqBybp7EkcJCrig63yE2E7PuNVOmilVMRcx/O+QDzGULTrKsq4DV13gSfak9ObPrWaHl/9bL5YcWw==} + engines: {node: '>=18.0.0'} + + '@smithy/types@4.9.0': + resolution: {integrity: sha512-MvUbdnXDTwykR8cB1WZvNNwqoWVaTRA0RLlLmf/cIFNMM2cKWz01X4Ly6SMC4Kks30r8tT3Cty0jmeWfiuyHTA==} + engines: {node: '>=18.0.0'} + + '@smithy/util-buffer-from@2.2.0': + resolution: {integrity: sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==} + engines: {node: '>=14.0.0'} + + '@smithy/util-buffer-from@4.2.0': + resolution: {integrity: sha512-kAY9hTKulTNevM2nlRtxAG2FQ3B2OR6QIrPY3zE5LqJy1oxzmgBGsHLWTcNhWXKchgA0WHW+mZkQrng/pgcCew==} + engines: {node: '>=18.0.0'} + + '@smithy/util-hex-encoding@4.2.0': + resolution: {integrity: sha512-CCQBwJIvXMLKxVbO88IukazJD9a4kQ9ZN7/UMGBjBcJYvatpWk+9g870El4cB8/EJxfe+k+y0GmR9CAzkF+Nbw==} + engines: {node: '>=18.0.0'} + + '@smithy/util-utf8@2.3.0': + resolution: {integrity: sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==} + engines: {node: '>=14.0.0'} + + '@smithy/util-utf8@4.2.0': + resolution: {integrity: sha512-zBPfuzoI8xyBtR2P6WQj63Rz8i3AmfAaJLuNG8dWsfvPe8lO4aCPYLn879mEgHndZH1zQ2oXmG8O1GGzzaoZiw==} + engines: {node: '>=18.0.0'} + + '@standard-schema/spec@1.1.0': + resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==} + + '@types/body-parser@1.19.6': + resolution: {integrity: sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==} + + '@types/chai@5.2.3': + resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==} + + '@types/connect@3.4.38': + resolution: {integrity: sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==} + + '@types/deep-eql@4.0.2': + resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==} + + '@types/estree@1.0.8': + resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==} + + '@types/express-serve-static-core@5.1.0': + resolution: {integrity: sha512-jnHMsrd0Mwa9Cf4IdOzbz543y4XJepXrbia2T4b6+spXC2We3t1y6K44D3mR8XMFSXMCf3/l7rCgddfx7UNVBA==} + + '@types/express@5.0.5': + resolution: {integrity: sha512-LuIQOcb6UmnF7C1PCFmEU1u2hmiHL43fgFQX67sN3H4Z+0Yk0Neo++mFsBjhOAuLzvlQeqAAkeDOZrJs9rzumQ==} + + '@types/figlet@1.7.0': + resolution: {integrity: sha512-KwrT7p/8Eo3Op/HBSIwGXOsTZKYiM9NpWRBJ5sVjWP/SmlS+oxxRvJht/FNAtliJvja44N3ul1yATgohnVBV0Q==} + + '@types/http-errors@2.0.5': + resolution: {integrity: sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==} + + '@types/json-schema@7.0.15': + resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==} + + '@types/mime@1.3.5': + resolution: {integrity: sha512-/pyBZWSLD2n0dcHE3hq8s8ZvcETHtEuF+3E7XVt0Ig2nvsVQXdghHVcEkIWjy9A0wKfTn97a/PSDYohKIlnP/w==} + + '@types/node@12.20.55': + resolution: {integrity: sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==} + + '@types/node@22.19.7': + resolution: {integrity: sha512-MciR4AKGHWl7xwxkBa6xUGxQJ4VBOmPTF7sL+iGzuahOFaO0jHCsuEfS80pan1ef4gWId1oWOweIhrDEYLuaOw==} + + '@types/node@25.0.3': + resolution: {integrity: sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==} + + '@types/node@25.9.1': + resolution: {integrity: sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg==} + + '@types/qs@6.14.0': + resolution: {integrity: sha512-eOunJqu0K1923aExK6y8p6fsihYEn/BYuQ4g0CxAAgFc4b/ZLN4CrsRZ55srTdqoiLzU2B2evC+apEIxprEzkQ==} + + '@types/range-parser@1.2.7': + resolution: {integrity: sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==} + + '@types/retry@0.12.0': + resolution: {integrity: sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==} + + '@types/send@0.17.6': + resolution: {integrity: sha512-Uqt8rPBE8SY0RK8JB1EzVOIZ32uqy8HwdxCnoCOsYrvnswqmFZ/k+9Ikidlk/ImhsdvBsloHbAlewb2IEBV/Og==} + + '@types/send@1.2.1': + resolution: {integrity: sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==} + + '@types/serve-static@1.15.10': + resolution: {integrity: sha512-tRs1dB+g8Itk72rlSI2ZrW6vZg0YrLI81iQSTkMmOqnqCaNr/8Ek4VwWcN5vZgCYWbg/JJSGBlUaYGAOP73qBw==} + + '@typescript-eslint/eslint-plugin@8.47.0': + resolution: {integrity: sha512-fe0rz9WJQ5t2iaLfdbDc9T80GJy0AeO453q8C3YCilnGozvOyCG5t+EZtg7j7D88+c3FipfP/x+wzGnh1xp8ZA==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + '@typescript-eslint/parser': ^8.47.0 + eslint: ^8.57.0 || ^9.0.0 + typescript: '>=4.8.4 <6.0.0' + + '@typescript-eslint/parser@8.47.0': + resolution: {integrity: sha512-lJi3PfxVmo0AkEY93ecfN+r8SofEqZNGByvHAI3GBLrvt1Cw6H5k1IM02nSzu0RfUafr2EvFSw0wAsZgubNplQ==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + eslint: ^8.57.0 || ^9.0.0 + typescript: '>=4.8.4 <6.0.0' + + '@typescript-eslint/project-service@8.47.0': + resolution: {integrity: sha512-2X4BX8hUeB5JcA1TQJ7GjcgulXQ+5UkNb0DL8gHsHUHdFoiCTJoYLTpib3LtSDPZsRET5ygN4qqIWrHyYIKERA==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + typescript: '>=4.8.4 <6.0.0' + + '@typescript-eslint/scope-manager@8.47.0': + resolution: {integrity: sha512-a0TTJk4HXMkfpFkL9/WaGTNuv7JWfFTQFJd6zS9dVAjKsojmv9HT55xzbEpnZoY+VUb+YXLMp+ihMLz/UlZfDg==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@typescript-eslint/tsconfig-utils@8.47.0': + resolution: {integrity: sha512-ybUAvjy4ZCL11uryalkKxuT3w3sXJAuWhOoGS3T/Wu+iUu1tGJmk5ytSY8gbdACNARmcYEB0COksD2j6hfGK2g==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + typescript: '>=4.8.4 <6.0.0' + + '@typescript-eslint/type-utils@8.47.0': + resolution: {integrity: sha512-QC9RiCmZ2HmIdCEvhd1aJELBlD93ErziOXXlHEZyuBo3tBiAZieya0HLIxp+DoDWlsQqDawyKuNEhORyku+P8A==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + eslint: ^8.57.0 || ^9.0.0 + typescript: '>=4.8.4 <6.0.0' + + '@typescript-eslint/types@8.47.0': + resolution: {integrity: sha512-nHAE6bMKsizhA2uuYZbEbmp5z2UpffNrPEqiKIeN7VsV6UY/roxanWfoRrf6x/k9+Obf+GQdkm0nPU+vnMXo9A==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@typescript-eslint/typescript-estree@8.47.0': + resolution: {integrity: sha512-k6ti9UepJf5NpzCjH31hQNLHQWupTRPhZ+KFF8WtTuTpy7uHPfeg2NM7cP27aCGajoEplxJDFVCEm9TGPYyiVg==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + typescript: '>=4.8.4 <6.0.0' + + '@typescript-eslint/utils@8.47.0': + resolution: {integrity: sha512-g7XrNf25iL4TJOiPqatNuaChyqt49a/onq5YsJ9+hXeugK+41LVg7AxikMfM02PC6jbNtZLCJj6AUcQXJS/jGQ==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + eslint: ^8.57.0 || ^9.0.0 + typescript: '>=4.8.4 <6.0.0' + + '@typescript-eslint/visitor-keys@8.47.0': + resolution: {integrity: sha512-SIV3/6eftCy1bNzCQoPmbWsRLujS8t5iDIZ4spZOBHqrM+yfX2ogg8Tt3PDTAVKw3sSCiUgg30uOAvK2r9zGjQ==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + '@upstash/redis@1.38.0': + resolution: {integrity: sha512-wu+dZBptlLy0+MCUEoHmzrY/TnmgDey3+c7EbIGwrLqAvkP8yi5MWZHYGIFtAygmL4Bkz2TdFu+eU0vFPncIcg==} + + '@vercel/oidc@3.1.0': + resolution: {integrity: sha512-Fw28YZpRnA3cAHHDlkt7xQHiJ0fcL+NRcIqsocZQUSmbzeIKRpwttJjik5ZGanXP+vlA4SbTg+AbA3bP363l+w==} + engines: {node: '>= 20'} + + '@vitest/expect@4.1.9': + resolution: {integrity: sha512-vl/rYsUKcBr3SnQn166+XR5ZQcgMx3DQhFWdfli/cWpLnLUmbxZvyrJZotLFUryib+LtArYMSTJ5RbQ57ZqrlA==} + + '@vitest/mocker@4.1.9': + resolution: {integrity: sha512-EVkXzBjrPGM+cK8/ANWgBrkUCfJfb38/EfTSO8h7pWvKkyPkpWxvR7BkD2MyItMF62C97zAEoqdpUixwR/e+Rw==} + peerDependencies: + msw: ^2.4.9 + vite: ^6.0.0 || ^7.0.0 || ^8.0.0 + peerDependenciesMeta: + msw: + optional: true + vite: + optional: true + + '@vitest/pretty-format@4.1.9': + resolution: {integrity: sha512-s0iufns3iIFitdgm+YR7g1whCAaGtXz459VS9/PqyKDEEFgYIhsHOQmXgIgDuYCt7DeQmiZT0Qe2OA2p4ZPu5A==} + + '@vitest/runner@4.1.9': + resolution: {integrity: sha512-KXLMDtc7oe70+3mJfGrPUWPesswH+3sTxAMAMl8DG7I8IUQT4XW718dY5ID3vPUcmlu27CcKfY4P3h3I29SLJg==} + + '@vitest/snapshot@4.1.9': + resolution: {integrity: sha512-Jc7RKGNBo8Z28WYIm0Niej4xdSPByRf6mU58VpHQkd6Zh05rlnA+twjbK5HyeIGHxrzsc3mJgS43uM0CZKzaIA==} + + '@vitest/spy@4.1.9': + resolution: {integrity: sha512-fHpsS6mIi+PiEW+vcRVOMkX1oSaPKne3VOclSFICPcGOmfKgXPU5iAah+wcNcj2xPrCCmfq99IDGf+EojhhvhA==} + + '@vitest/utils@4.1.9': + resolution: {integrity: sha512-A51o8ymO5PpqlWNnBP9ZHPXDIpuMtTLlGSjN7la4US+LJzoUMyhwjA5QXlm39JexgwHKW4Xjs8Z2d3dLCXOeuA==} + + accepts@2.0.0: + resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==} + engines: {node: '>= 0.6'} + + acorn-jsx@5.3.2: + resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==} + peerDependencies: + acorn: ^6.0.0 || ^7.0.0 || ^8.0.0 + + acorn@8.15.0: + resolution: {integrity: sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==} + engines: {node: '>=0.4.0'} + hasBin: true + + acorn@8.16.0: + resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==} + engines: {node: '>=0.4.0'} + hasBin: true + + agent-base@7.1.4: + resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==} + engines: {node: '>= 14'} + + ai@6.0.23: + resolution: {integrity: sha512-IV8hqp6sQvZ0XVlu8bCnFlwG7+2d40ff26RZ1k4yw/zVuk2F6SXlONURtTo9vwPOPYeF7auXvyPA+dMDoepWxg==} + engines: {node: '>=18'} + peerDependencies: + zod: ^3.25.76 || ^4.1.8 + + ajv-formats@3.0.1: + resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==} + peerDependencies: + ajv: ^8.0.0 + peerDependenciesMeta: + ajv: + optional: true + + ajv@6.15.0: + resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==} + + ajv@8.17.1: + resolution: {integrity: sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==} + + ansi-align@3.0.1: + resolution: {integrity: sha512-IOfwwBF5iczOjp/WeY4YxyjqAFMQoZufdQWDd19SEExbVLNXqvpzSJ/M7Za4/sCPmQ0+GRquoA7bGcINcxew6w==} + + ansi-colors@4.1.3: + resolution: {integrity: sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==} + engines: {node: '>=6'} + + ansi-regex@5.0.1: + resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==} + engines: {node: '>=8'} + + ansi-regex@6.2.2: + resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==} + engines: {node: '>=12'} + + ansi-styles@4.3.0: + resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==} + engines: {node: '>=8'} + + ansi-styles@6.2.3: + resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==} + engines: {node: '>=12'} + + any-promise@1.3.0: + resolution: {integrity: sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==} + + argparse@1.0.10: + resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==} + + argparse@2.0.1: + resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} + + array-union@2.1.0: + resolution: {integrity: sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==} + engines: {node: '>=8'} + + assertion-error@2.0.1: + resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==} + engines: {node: '>=12'} + + aws4fetch@1.0.20: + resolution: {integrity: sha512-/djoAN709iY65ETD6LKCtyyEI04XIBP5xVvfmNxsEP0uJB5tyaGBztSryRr4HqMStr9R06PisQE7m9zDTXKu6g==} + + balanced-match@1.0.2: + resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==} + + balanced-match@4.0.4: + resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==} + engines: {node: 18 || 20 || >=22} + + base64-js@1.5.1: + resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==} + + better-path-resolve@1.0.0: + resolution: {integrity: sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==} + engines: {node: '>=4'} + + bignumber.js@9.3.1: + resolution: {integrity: sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==} + + body-parser@2.2.0: + resolution: {integrity: sha512-02qvAaxv8tp7fBa/mw1ga98OGm+eCbqzJOKoRt70sLmfEEi+jyBYVTDGfCL/k06/4EMk/z01gCe7HoCH/f2LTg==} + engines: {node: '>=18'} + + body-parser@2.2.2: + resolution: {integrity: sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==} + engines: {node: '>=18'} + + bowser@2.14.1: + resolution: {integrity: sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==} + + boxen@8.0.1: + resolution: {integrity: sha512-F3PH5k5juxom4xktynS7MoFY+NUWH5LC4CnH11YB8NPew+HLpmBLCybSAEyb2F+4pRXhuhWqFesoQd6DAyc2hw==} + engines: {node: '>=18'} + + brace-expansion@1.1.15: + resolution: {integrity: sha512-EwOCDEex4quD37XhqM3omwtMoJjr//isUZz1JopUNWms+4Z2ViyM/k1YIRePpoVNnQhENnxtFjLaxNHrT7xIUg==} + + brace-expansion@2.0.2: + resolution: {integrity: sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==} + + brace-expansion@5.0.6: + resolution: {integrity: sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==} + engines: {node: 18 || 20 || >=22} + + braces@3.0.3: + resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==} + engines: {node: '>=8'} + + buffer-equal-constant-time@1.0.1: + resolution: {integrity: sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==} + + bundle-name@4.1.0: + resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==} + engines: {node: '>=18'} + + bundle-require@5.1.0: + resolution: {integrity: sha512-3WrrOuZiyaaZPWiEt4G3+IffISVC9HYlWueJEBWED4ZH4aIAC2PnkdnuRrR94M+w6yGWn4AglWtJtBI8YqvgoA==} + engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0} + peerDependencies: + esbuild: '>=0.18' + + bytes@3.1.2: + resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==} + engines: {node: '>= 0.8'} + + cac@6.7.14: + resolution: {integrity: sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==} + engines: {node: '>=8'} + + call-bind-apply-helpers@1.0.2: + resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==} + engines: {node: '>= 0.4'} + + call-bound@1.0.4: + resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==} + engines: {node: '>= 0.4'} + + callsites@3.1.0: + resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==} + engines: {node: '>=6'} + + camelcase@8.0.0: + resolution: {integrity: sha512-8WB3Jcas3swSvjIeA2yvCJ+Miyz5l1ZmB6HFb9R1317dt9LCQoswg/BGrmAmkWVEszSrrg4RwmO46qIm2OEnSA==} + engines: {node: '>=16'} + + chai@6.2.2: + resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==} + engines: {node: '>=18'} + + chalk@4.1.2: + resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==} + engines: {node: '>=10'} + + chalk@5.6.2: + resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==} + engines: {node: ^12.17.0 || ^14.13 || >=16.0.0} + + chardet@2.1.1: + resolution: {integrity: sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ==} + + chokidar@4.0.3: + resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==} + engines: {node: '>= 14.16.0'} + + ci-info@3.9.0: + resolution: {integrity: sha512-NIxF55hv4nSqQswkAeiOi1r83xy8JldOFDTWiug55KBu9Jnblncd2U6ViHmYgHf01TPZS77NJBhBMKdWj9HQMQ==} + engines: {node: '>=8'} + + cli-boxes@3.0.0: + resolution: {integrity: sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==} + engines: {node: '>=10'} + + cli-cursor@5.0.0: + resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==} + engines: {node: '>=18'} + + cli-spinners@3.4.0: + resolution: {integrity: sha512-bXfOC4QcT1tKXGorxL3wbJm6XJPDqEnij2gQ2m7ESQuE+/z9YFIWnl/5RpTiKWbMq3EVKR4fRLJGn6DVfu0mpw==} + engines: {node: '>=18.20'} + + cli-width@4.1.0: + resolution: {integrity: sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==} + engines: {node: '>= 12'} + + color-convert@2.0.1: + resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==} + engines: {node: '>=7.0.0'} + + color-name@1.1.4: + resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==} + + commander@13.1.0: + resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==} + engines: {node: '>=18'} + + commander@14.0.2: + resolution: {integrity: sha512-TywoWNNRbhoD0BXs1P3ZEScW8W5iKrnbithIl0YH+uCmBd0QpPOA8yc82DS3BIE5Ma6FnBVUsJ7wVUDz4dvOWQ==} + engines: {node: '>=20'} + + commander@15.0.0: + resolution: {integrity: sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==} + engines: {node: '>=22.12.0'} + + commander@4.1.1: + resolution: {integrity: sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==} + engines: {node: '>= 6'} + + concat-map@0.0.1: + resolution: {integrity: sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==} + + confbox@0.1.8: + resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==} + + consola@3.4.2: + resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==} + engines: {node: ^14.18.0 || >=16.10.0} + + content-disposition@1.0.1: + resolution: {integrity: sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q==} + engines: {node: '>=18'} + + content-type@1.0.5: + resolution: {integrity: sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==} + engines: {node: '>= 0.6'} + + convert-source-map@2.0.0: + resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==} + + cookie-signature@1.2.2: + resolution: {integrity: sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==} + engines: {node: '>=6.6.0'} + + cookie@0.7.2: + resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==} + engines: {node: '>= 0.6'} + + cors@2.8.5: + resolution: {integrity: sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g==} + engines: {node: '>= 0.10'} + + cross-spawn@7.0.6: + resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==} + engines: {node: '>= 8'} + + data-uri-to-buffer@4.0.1: + resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==} + engines: {node: '>= 12'} + + debug@4.4.3: + resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==} + engines: {node: '>=6.0'} + peerDependencies: + supports-color: '*' + peerDependenciesMeta: + supports-color: + optional: true + + deep-is@0.1.4: + resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==} + + default-browser-id@5.0.1: + resolution: {integrity: sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==} + engines: {node: '>=18'} + + default-browser@5.4.0: + resolution: {integrity: sha512-XDuvSq38Hr1MdN47EDvYtx3U0MTqpCEn+F6ft8z2vYDzMrvQhVp0ui9oQdqW3MvK3vqUETglt1tVGgjLuJ5izg==} + engines: {node: '>=18'} + + define-lazy-prop@3.0.0: + resolution: {integrity: sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==} + engines: {node: '>=12'} + + depd@2.0.0: + resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==} + engines: {node: '>= 0.8'} + + detect-indent@6.1.0: + resolution: {integrity: sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==} + engines: {node: '>=8'} + + diff@8.0.4: + resolution: {integrity: sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==} + engines: {node: '>=0.3.1'} + + dir-glob@3.0.1: + resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==} + engines: {node: '>=8'} + + dotenv@17.4.2: + resolution: {integrity: sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==} + engines: {node: '>=12'} + + dunder-proto@1.0.1: + resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==} + engines: {node: '>= 0.4'} + + ecdsa-sig-formatter@1.0.11: + resolution: {integrity: sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==} + + ee-first@1.1.1: + resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==} + + emoji-regex@10.6.0: + resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==} + + emoji-regex@8.0.0: + resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==} + + encodeurl@2.0.0: + resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==} + engines: {node: '>= 0.8'} + + enquirer@2.4.1: + resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==} + engines: {node: '>=8.6'} + + es-define-property@1.0.1: + resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==} + engines: {node: '>= 0.4'} + + es-errors@1.3.0: + resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==} + engines: {node: '>= 0.4'} + + es-module-lexer@2.3.0: + resolution: {integrity: sha512-KLdwQm2NvGLDkQDCGvmiQrhkd0JbMzXthwQAUgWjQuQdBLFa3eiBP5arXZyA+f8x+x7OXgud6bq2rxjGtHV2tw==} + + es-object-atoms@1.1.1: + resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==} + engines: {node: '>= 0.4'} + + esbuild@0.25.12: + resolution: {integrity: sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==} + engines: {node: '>=18'} + hasBin: true + + esbuild@0.27.0: + resolution: {integrity: sha512-jd0f4NHbD6cALCyGElNpGAOtWxSq46l9X/sWB0Nzd5er4Kz2YTm+Vl0qKFT9KUJvD8+fiO8AvoHhFvEatfVixA==} + engines: {node: '>=18'} + hasBin: true + + escape-html@1.0.3: + resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==} + + escape-string-regexp@4.0.0: + resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==} + engines: {node: '>=10'} + + eslint-config-prettier@10.1.8: + resolution: {integrity: sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w==} + hasBin: true + peerDependencies: + eslint: '>=7.0.0' + + eslint-plugin-prettier@5.5.6: + resolution: {integrity: sha512-ifetmTcxWfz+4qRW3pH/ujdTq2jQIj59AxJMIN26K5avYgU8dxycUETQonWiW+wPrYXA0j3Try0l1CnwVQtDqQ==} + engines: {node: ^14.18.0 || >=16.0.0} + peerDependencies: + '@types/eslint': '>=8.0.0' + eslint: '>=8.0.0' + eslint-config-prettier: '>= 7.0.0 <10.0.0 || >=10.1.0' + prettier: '>=3.0.0' + peerDependenciesMeta: + '@types/eslint': + optional: true + eslint-config-prettier: + optional: true + + eslint-scope@8.4.0: + resolution: {integrity: sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + eslint-visitor-keys@3.4.3: + resolution: {integrity: sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==} + engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0} + + eslint-visitor-keys@4.2.1: + resolution: {integrity: sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + eslint@9.39.4: + resolution: {integrity: sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + hasBin: true + peerDependencies: + jiti: '*' + peerDependenciesMeta: + jiti: + optional: true + + espree@10.4.0: + resolution: {integrity: sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + + esprima@4.0.1: + resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==} + engines: {node: '>=4'} + hasBin: true + + esquery@1.7.0: + resolution: {integrity: sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==} + engines: {node: '>=0.10'} + + esrecurse@4.3.0: + resolution: {integrity: sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==} + engines: {node: '>=4.0'} + + estraverse@5.3.0: + resolution: {integrity: sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==} + engines: {node: '>=4.0'} + + estree-walker@3.0.3: + resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==} + + esutils@2.0.3: + resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==} + engines: {node: '>=0.10.0'} + + etag@1.8.1: + resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==} + engines: {node: '>= 0.6'} + + eventsource-parser@3.0.6: + resolution: {integrity: sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==} + engines: {node: '>=18.0.0'} + + eventsource@3.0.7: + resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==} + engines: {node: '>=18.0.0'} + + expect-type@1.4.0: + resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==} + engines: {node: '>=12.0.0'} + + express-rate-limit@8.5.2: + resolution: {integrity: sha512-5Kb34ipNX694DH48vN9irak1Qx30nb0PLYHXfJgw4YEjiC3ZEmZJhwOp+VfiCYwFzvFTdB9QkArYS5kXa2cx2A==} + engines: {node: '>= 16'} + peerDependencies: + express: '>= 4.11' + + express@5.1.0: + resolution: {integrity: sha512-DT9ck5YIRU+8GYzzU5kT3eHGA5iL+1Zd0EutOmTE9Dtk+Tvuzd23VBU+ec7HPNSTxXYO55gPV/hq4pSBJDjFpA==} + engines: {node: '>= 18'} + + express@5.2.1: + resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==} + engines: {node: '>= 18'} + + extend@3.0.2: + resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==} + + extendable-error@0.1.7: + resolution: {integrity: sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg==} + + fast-deep-equal@3.1.3: + resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==} + + fast-diff@1.3.0: + resolution: {integrity: sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw==} + + fast-glob@3.3.3: + resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==} + engines: {node: '>=8.6.0'} + + fast-json-stable-stringify@2.1.0: + resolution: {integrity: sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==} + + fast-levenshtein@2.0.6: + resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==} + + fast-uri@3.1.0: + resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==} + + fast-xml-builder@1.2.0: + resolution: {integrity: sha512-00aAWieqff+ZJhsXA4g1g7M8k+7AYoMUUHF+/zFb5U6Uv/P0Vl4QZo84/IcufzYalLuEj9928bXN9PbbFzMF0Q==} + + fast-xml-parser@5.7.3: + resolution: {integrity: sha512-C0AaNuC+mscy6vrAQKAc/rMq+zAPHodfHGZu4sGVehvAQt/JLG1O5zEcYcXSY5zSqr4YVgxsB+pHXTq0i7eDlg==} + hasBin: true + + fastq@1.19.1: + resolution: {integrity: sha512-GwLTyxkCXjXbxqIhTsMI2Nui8huMPtnxg7krajPJAjnEG/iiOS7i+zCtWGZR9G0NBKbXKh6X9m9UIsYX/N6vvQ==} + + fdir@6.5.0: + resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==} + engines: {node: '>=12.0.0'} + peerDependencies: + picomatch: ^3 || ^4 + peerDependenciesMeta: + picomatch: + optional: true + + fetch-blob@3.2.0: + resolution: {integrity: sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==} + engines: {node: ^12.20 || >= 14.13} + + figlet@1.9.4: + resolution: {integrity: sha512-uN6QE+TrzTAHC1IWTyrc4FfGo2KH/82J8Jl1tyKB7+z5DBit/m3D++Iu5lg91qJMnQQ3vpJrj5gxcK/pk4R9tQ==} + engines: {node: '>= 17.0.0'} + hasBin: true + + file-entry-cache@8.0.0: + resolution: {integrity: sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==} + engines: {node: '>=16.0.0'} + + fill-range@7.1.1: + resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==} + engines: {node: '>=8'} + + finalhandler@2.1.0: + resolution: {integrity: sha512-/t88Ty3d5JWQbWYgaOGCCYfXRwV1+be02WqYYlL6h0lEiUAMPM8o8qKGO01YIkOHzka2up08wvgYD0mDiI+q3Q==} + engines: {node: '>= 0.8'} + + find-up@4.1.0: + resolution: {integrity: sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==} + engines: {node: '>=8'} + + find-up@5.0.0: + resolution: {integrity: sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==} + engines: {node: '>=10'} + + fix-dts-default-cjs-exports@1.0.1: + resolution: {integrity: sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==} + + flat-cache@4.0.1: + resolution: {integrity: sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==} + engines: {node: '>=16'} + + flatted@3.3.3: + resolution: {integrity: sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==} + + formdata-polyfill@4.0.10: + resolution: {integrity: sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==} + engines: {node: '>=12.20.0'} + + forwarded@0.2.0: + resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==} + engines: {node: '>= 0.6'} + + fresh@2.0.0: + resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==} + engines: {node: '>= 0.8'} + + fs-extra@7.0.1: + resolution: {integrity: sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==} + engines: {node: '>=6 <7 || >=8'} + + fs-extra@8.1.0: + resolution: {integrity: sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==} + engines: {node: '>=6 <7 || >=8'} + + fsevents@2.3.3: + resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==} + engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} + os: [darwin] + + function-bind@1.1.2: + resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==} + + gaxios@7.1.4: + resolution: {integrity: sha512-bTIgTsM2bWn3XklZISBTQX7ZSddGW+IO3bMdGaemHZ3tbqExMENHLx6kKZ/KlejgrMtj8q7wBItt51yegqalrA==} + engines: {node: '>=18'} + + gcp-metadata@8.1.2: + resolution: {integrity: sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==} + engines: {node: '>=18'} + + get-east-asian-width@1.6.0: + resolution: {integrity: sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==} + engines: {node: '>=18'} + + get-intrinsic@1.3.0: + resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==} + engines: {node: '>= 0.4'} + + get-proto@1.0.1: + resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==} + engines: {node: '>= 0.4'} + + get-tsconfig@4.14.0: + resolution: {integrity: sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==} + + glob-parent@5.1.2: + resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==} + engines: {node: '>= 6'} + + glob-parent@6.0.2: + resolution: {integrity: sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==} + engines: {node: '>=10.13.0'} + + glob@13.0.6: + resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==} + engines: {node: 18 || 20 || >=22} + + globals@14.0.0: + resolution: {integrity: sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==} + engines: {node: '>=18'} + + globby@11.1.0: + resolution: {integrity: sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==} + engines: {node: '>=10'} + + google-auth-library@10.6.2: + resolution: {integrity: sha512-e27Z6EThmVNNvtYASwQxose/G57rkRuaRbQyxM2bvYLLX/GqWZ5chWq2EBoUchJbCc57eC9ArzO5wMsEmWftCw==} + engines: {node: '>=18'} + + google-logging-utils@1.1.3: + resolution: {integrity: sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==} + engines: {node: '>=14'} + + gopd@1.2.0: + resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==} + engines: {node: '>= 0.4'} + + graceful-fs@4.2.11: + resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==} + + graphemer@1.4.0: + resolution: {integrity: sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag==} + + has-flag@4.0.0: + resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==} + engines: {node: '>=8'} + + has-symbols@1.1.0: + resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==} + engines: {node: '>= 0.4'} + + hasown@2.0.2: + resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==} + engines: {node: '>= 0.4'} + + highlight.js@10.7.3: + resolution: {integrity: sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==} + + hono@4.12.23: + resolution: {integrity: sha512-eIaZ9qDgu7XV0pxOCrg7/WhnQ6Ivm22UcxhXx/A3dcbqbbYgBEkc6e/J/s7j2tS96zoB0S9VBdLwQNCWwUo4LA==} + engines: {node: '>=16.9.0'} + + hosted-git-info@9.0.3: + resolution: {integrity: sha512-Hc+ghLoSt6QaYZUv0WBiIvmMDZuZZ7oaDvdH8MbfOO4lOsxdXLEvuC6ePoGs9H1X9oCLyq6+NVN0MKqD+ydxyg==} + engines: {node: ^20.17.0 || >=22.9.0} + + http-errors@2.0.1: + resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==} + engines: {node: '>= 0.8'} + + http-proxy-agent@7.0.2: + resolution: {integrity: sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==} + engines: {node: '>= 14'} + + https-proxy-agent@7.0.6: + resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==} + engines: {node: '>= 14'} + + human-id@4.1.3: + resolution: {integrity: sha512-tsYlhAYpjCKa//8rXZ9DqKEawhPoSytweBC2eNvcaDK+57RZLHGqNs3PZTQO6yekLFSuvA6AlnAfrw1uBvtb+Q==} + hasBin: true + + iconv-lite@0.6.3: + resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==} + engines: {node: '>=0.10.0'} + + iconv-lite@0.7.0: + resolution: {integrity: sha512-cf6L2Ds3h57VVmkZe+Pn+5APsT7FpqJtEhhieDCvrE2MK5Qk9MyffgQyuxQTm6BChfeZNtcOLHp9IcWRVcIcBQ==} + engines: {node: '>=0.10.0'} + + iconv-lite@0.7.2: + resolution: {integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==} + engines: {node: '>=0.10.0'} + + ignore@5.3.2: + resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==} + engines: {node: '>= 4'} + + ignore@7.0.5: + resolution: {integrity: sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==} + engines: {node: '>= 4'} + + import-fresh@3.3.1: + resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==} + engines: {node: '>=6'} + + imurmurhash@0.1.4: + resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==} + engines: {node: '>=0.8.19'} + + inherits@2.0.4: + resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==} + + ip-address@10.2.0: + resolution: {integrity: sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==} + engines: {node: '>= 12'} + + ipaddr.js@1.9.1: + resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==} + engines: {node: '>= 0.10'} + + is-docker@3.0.0: + resolution: {integrity: sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==} + engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0} + hasBin: true + + is-extglob@2.1.1: + resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==} + engines: {node: '>=0.10.0'} + + is-fullwidth-code-point@3.0.0: + resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==} + engines: {node: '>=8'} + + is-glob@4.0.3: + resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==} + engines: {node: '>=0.10.0'} + + is-inside-container@1.0.0: + resolution: {integrity: sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==} + engines: {node: '>=14.16'} + hasBin: true + + is-interactive@2.0.0: + resolution: {integrity: sha512-qP1vozQRI+BMOPcjFzrjXuQvdak2pHNUMZoeG2eRbiSqyvbEf/wQtEOTOX1guk6E3t36RkaqiSt8A/6YElNxLQ==} + engines: {node: '>=12'} + + is-number@7.0.0: + resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==} + engines: {node: '>=0.12.0'} + + is-promise@4.0.0: + resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==} + + is-subdir@1.2.0: + resolution: {integrity: sha512-2AT6j+gXe/1ueqbW6fLZJiIw3F8iXGJtt0yDrZaBhAZEG1raiTxKWU+IPqMCzQAXOUCKdA4UDMgacKH25XG2Cw==} + engines: {node: '>=4'} + + is-unicode-supported@2.1.0: + resolution: {integrity: sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==} + engines: {node: '>=18'} + + is-windows@1.0.2: + resolution: {integrity: sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA==} + engines: {node: '>=0.10.0'} + + is-wsl@3.1.0: + resolution: {integrity: sha512-UcVfVfaK4Sc4m7X3dUSoHoozQGBEFeDC+zVo06t98xe8CzHSZZBekNXH+tu0NalHolcJ/QAGqS46Hef7QXBIMw==} + engines: {node: '>=16'} + + isexe@2.0.0: + resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==} + + jiti@2.7.0: + resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==} + hasBin: true + + jose@6.2.3: + resolution: {integrity: sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==} + + joycon@3.1.1: + resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==} + engines: {node: '>=10'} + + js-yaml@3.14.2: + resolution: {integrity: sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==} + hasBin: true + + js-yaml@4.1.1: + resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==} + hasBin: true + + json-bigint@1.0.0: + resolution: {integrity: sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==} + + json-buffer@3.0.1: + resolution: {integrity: sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==} + + json-schema-to-ts@3.1.1: + resolution: {integrity: sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==} + engines: {node: '>=16'} + + json-schema-traverse@0.4.1: + resolution: {integrity: sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==} + + json-schema-traverse@1.0.0: + resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==} + + json-schema-typed@8.0.2: + resolution: {integrity: sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==} + + json-schema@0.4.0: + resolution: {integrity: sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA==} + + json-stable-stringify-without-jsonify@1.0.1: + resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==} + + jsonfile@4.0.0: + resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==} + + jwa@2.0.1: + resolution: {integrity: sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==} + + jws@4.0.1: + resolution: {integrity: sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==} + + keyv@4.5.4: + resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==} + + levn@0.4.1: + resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==} + engines: {node: '>= 0.8.0'} + + lilconfig@3.1.3: + resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==} + engines: {node: '>=14'} + + lines-and-columns@1.2.4: + resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==} + + load-tsconfig@0.2.5: + resolution: {integrity: sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==} + engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0} + + locate-path@5.0.0: + resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==} + engines: {node: '>=8'} + + locate-path@6.0.0: + resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==} + engines: {node: '>=10'} + + lodash.merge@4.6.2: + resolution: {integrity: sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==} + + lodash.startcase@4.4.0: + resolution: {integrity: sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==} + + log-symbols@7.0.1: + resolution: {integrity: sha512-ja1E3yCr9i/0hmBVaM0bfwDjnGy8I/s6PP4DFp+yP+a+mrHO4Rm7DtmnqROTUkHIkqffC84YY7AeqX6oFk0WFg==} + engines: {node: '>=18'} + + long@5.3.2: + resolution: {integrity: sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==} + + lru-cache@11.5.0: + resolution: {integrity: sha512-5YgH9UJd7wVb9hIouI2adWpgqrrICkt070Dnj8EUY1+B4B2P9eRLPAkAAo6NICA7CEhOIeBHl46u9zSNpNu7zA==} + engines: {node: 20 || >=22} + + magic-string@0.30.21: + resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==} + + marked@15.0.12: + resolution: {integrity: sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==} + engines: {node: '>= 18'} + hasBin: true + + math-intrinsics@1.1.0: + resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==} + engines: {node: '>= 0.4'} + + media-typer@1.1.0: + resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==} + engines: {node: '>= 0.8'} + + merge-descriptors@2.0.0: + resolution: {integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==} + engines: {node: '>=18'} + + merge2@1.4.1: + resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==} + engines: {node: '>= 8'} + + micromatch@4.0.8: + resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==} + engines: {node: '>=8.6'} + + mime-db@1.54.0: + resolution: {integrity: sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==} + engines: {node: '>= 0.6'} + + mime-types@3.0.2: + resolution: {integrity: sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==} + engines: {node: '>=18'} + + mimic-function@5.0.1: + resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==} + engines: {node: '>=18'} + + minimatch@10.2.5: + resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==} + engines: {node: 18 || 20 || >=22} + + minimatch@3.1.5: + resolution: {integrity: sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==} + + minimatch@9.0.5: + resolution: {integrity: sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==} + engines: {node: '>=16 || 14 >=14.17'} + + minipass@7.1.3: + resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==} + engines: {node: '>=16 || 14 >=14.17'} + + mlly@1.8.0: + resolution: {integrity: sha512-l8D9ODSRWLe2KHJSifWGwBqpTZXIXTeo8mlKjY+E2HAakaTeNpqAyBZ8GSqLzHgw4XmHmC8whvpjJNMbFZN7/g==} + + mri@1.2.0: + resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==} + engines: {node: '>=4'} + + ms@2.1.3: + resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==} + + mute-stream@3.0.0: + resolution: {integrity: sha512-dkEJPVvun4FryqBmZ5KhDo0K9iDXAwn08tMLDinNdRBNPcYEDiWYysLcc6k3mjTMlbP9KyylvRpd4wFtwrT9rw==} + engines: {node: ^20.17.0 || >=22.9.0} + + mz@2.7.0: + resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==} + + nanoid@3.3.11: + resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==} + engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1} + hasBin: true + + natural-compare@1.4.0: + resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==} + + negotiator@1.0.0: + resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==} + engines: {node: '>= 0.6'} + + node-domexception@1.0.0: + resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==} + engines: {node: '>=10.5.0'} + deprecated: Use your platform's native DOMException instead + + node-fetch@3.3.2: + resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==} + engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0} + + object-assign@4.1.1: + resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==} + engines: {node: '>=0.10.0'} + + object-inspect@1.13.4: + resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==} + engines: {node: '>= 0.4'} + + obug@2.1.1: + resolution: {integrity: sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==} + + on-finished@2.4.1: + resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==} + engines: {node: '>= 0.8'} + + once@1.4.0: + resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==} + + onetime@7.0.0: + resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==} + engines: {node: '>=18'} + + open@10.2.0: + resolution: {integrity: sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA==} + engines: {node: '>=18'} + + openai@6.26.0: + resolution: {integrity: sha512-zd23dbWTjiJ6sSAX6s0HrCZi41JwTA1bQVs0wLQPZ2/5o2gxOJA5wh7yOAUgwYybfhDXyhwlpeQf7Mlgx8EOCA==} + hasBin: true + peerDependencies: + ws: ^8.18.0 + zod: ^3.25 || ^4.0 + peerDependenciesMeta: + ws: + optional: true + zod: + optional: true + + optionator@0.9.4: + resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==} + engines: {node: '>= 0.8.0'} + + ora@9.4.0: + resolution: {integrity: sha512-84cglkRILFxdtA8hAvLNdMrtBpPNBTrQ9/ulg0FA7xLMnD6mifv+enAIeRmvtv+WgdCE+LPGOfQmtJRrVaIVhQ==} + engines: {node: '>=20'} + + outdent@0.5.0: + resolution: {integrity: sha512-/jHxFIzoMXdqPzTaCpFzAAWhpkSjZPF4Vsn6jAfNpmbH/ymsmd7Qc6VE9BGn0L6YMj6uwpQLxCECpus4ukKS9Q==} + + p-filter@2.1.0: + resolution: {integrity: sha512-ZBxxZ5sL2HghephhpGAQdoskxplTwr7ICaehZwLIlfL6acuVgZPm8yBNuRAFBGEqtD/hmUeq9eqLg2ys9Xr/yw==} + engines: {node: '>=8'} + + p-limit@2.3.0: + resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==} + engines: {node: '>=6'} + + p-limit@3.1.0: + resolution: {integrity: sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==} + engines: {node: '>=10'} + + p-locate@4.1.0: + resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==} + engines: {node: '>=8'} + + p-locate@5.0.0: + resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==} + engines: {node: '>=10'} + + p-map@2.1.0: + resolution: {integrity: sha512-y3b8Kpd8OAN444hxfBbFfj1FY/RjtTd8tzYwhUqNYXx0fXx2iX4maP4Qr6qhIKbQXI02wTLAda4fYUbDagTUFw==} + engines: {node: '>=6'} + + p-retry@4.6.2: + resolution: {integrity: sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==} + engines: {node: '>=8'} + + p-try@2.2.0: + resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==} + engines: {node: '>=6'} + + package-manager-detector@0.2.11: + resolution: {integrity: sha512-BEnLolu+yuz22S56CU1SUKq3XC3PkwD5wv4ikR4MfGvnRVcmzXR9DwSlW2fEamyTPyXHomBJRzgapeuBvRNzJQ==} + + parent-module@1.0.1: + resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==} + engines: {node: '>=6'} + + parseurl@1.3.3: + resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==} + engines: {node: '>= 0.8'} + + partial-json@0.1.7: + resolution: {integrity: sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==} + + path-exists@4.0.0: + resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==} + engines: {node: '>=8'} + + path-expression-matcher@1.5.0: + resolution: {integrity: sha512-cbrerZV+6rvdQrrD+iGMcZFEiiSrbv9Tfdkvnusy6y0x0GKBXREFg/Y65GhIfm0tnLntThhzCnfKwp1WRjeCyQ==} + engines: {node: '>=14.0.0'} + + path-key@3.1.1: + resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==} + engines: {node: '>=8'} + + path-scurry@2.0.2: + resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==} + engines: {node: 18 || 20 || >=22} + + path-to-regexp@8.3.0: + resolution: {integrity: sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==} + + path-type@4.0.0: + resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==} + engines: {node: '>=8'} + + pathe@2.0.3: + resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==} + + picocolors@1.1.1: + resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==} + + picomatch@2.3.1: + resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==} + engines: {node: '>=8.6'} + + picomatch@4.0.3: + resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==} + engines: {node: '>=12'} + + pify@4.0.1: + resolution: {integrity: sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==} + engines: {node: '>=6'} + + pirates@4.0.7: + resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==} + engines: {node: '>= 6'} + + pkce-challenge@5.0.0: + resolution: {integrity: sha512-ueGLflrrnvwB3xuo/uGob5pd5FN7l0MsLf0Z87o/UQmRtwjvfylfc9MurIxRAWywCYTgrvpXBcqjV4OfCYGCIQ==} + engines: {node: '>=16.20.0'} + + pkg-types@1.3.1: + resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==} + + postcss-load-config@6.0.1: + resolution: {integrity: sha512-oPtTM4oerL+UXmx+93ytZVN82RrlY/wPUV8IeDxFrzIjXOLF1pN+EmKPLbubvKHT2HC20xXsCAH2Z+CKV6Oz/g==} + engines: {node: '>= 18'} + peerDependencies: + jiti: '>=1.21.0' + postcss: '>=8.0.9' + tsx: ^4.8.1 + yaml: ^2.4.2 + peerDependenciesMeta: + jiti: + optional: true + postcss: + optional: true + tsx: + optional: true + yaml: + optional: true + + postcss@8.5.6: + resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==} + engines: {node: ^10 || ^12 || >=14} + + prelude-ls@1.2.1: + resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==} + engines: {node: '>= 0.8.0'} + + prettier-linter-helpers@1.0.1: + resolution: {integrity: sha512-SxToR7P8Y2lWmv/kTzVLC1t/GDI2WGjMwNhLLE9qtH8Q13C+aEmuRlzDst4Up4s0Wc8sF2M+J57iB3cMLqftfg==} + engines: {node: '>=6.0.0'} + + prettier@2.8.8: + resolution: {integrity: sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==} + engines: {node: '>=10.13.0'} + hasBin: true + + prettier@3.6.2: + resolution: {integrity: sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==} + engines: {node: '>=14'} + hasBin: true + + proper-lockfile@4.1.2: + resolution: {integrity: sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==} + + protobufjs@7.6.1: + resolution: {integrity: sha512-4K0myLaWL5EteuSAro91EGFgcfVgxb64Jx+7oDAY6GOkXD4M69yuSEljNcInGVCA5sOPxmZ/EqDLj2x0Q0+Ygg==} + engines: {node: '>=12.0.0'} + + proxy-addr@2.0.7: + resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==} + engines: {node: '>= 0.10'} + + punycode@2.3.1: + resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==} + engines: {node: '>=6'} + + qs@6.14.0: + resolution: {integrity: sha512-YWWTjgABSKcvs/nWBi9PycY/JiPJqOD4JA6o9Sej2AtvSGarXxKC3OQSk4pAarbdQlKAh5D4FCQkJNkW+GAn3w==} + engines: {node: '>=0.6'} + + qs@6.15.2: + resolution: {integrity: sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==} + engines: {node: '>=0.6'} + + quansync@0.2.11: + resolution: {integrity: sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA==} + + queue-microtask@1.2.3: + resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==} + + range-parser@1.2.1: + resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==} + engines: {node: '>= 0.6'} + + raw-body@3.0.2: + resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==} + engines: {node: '>= 0.10'} + + read-yaml-file@1.1.0: + resolution: {integrity: sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA==} + engines: {node: '>=6'} + + readdirp@4.1.2: + resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==} + engines: {node: '>= 14.18.0'} + + require-from-string@2.0.2: + resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==} + engines: {node: '>=0.10.0'} + + resolve-from@4.0.0: + resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==} + engines: {node: '>=4'} + + resolve-from@5.0.0: + resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==} + engines: {node: '>=8'} + + resolve-pkg-maps@1.0.0: + resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==} + + restore-cursor@5.1.0: + resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==} + engines: {node: '>=18'} + + retry@0.12.0: + resolution: {integrity: sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==} + engines: {node: '>= 4'} + + retry@0.13.1: + resolution: {integrity: sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==} + engines: {node: '>= 4'} + + reusify@1.1.0: + resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==} + engines: {iojs: '>=1.0.0', node: '>=0.10.0'} + + rollup@4.53.3: + resolution: {integrity: sha512-w8GmOxZfBmKknvdXU1sdM9NHcoQejwF/4mNgj2JuEEdRaHwwF12K7e9eXn1nLZ07ad+du76mkVsyeb2rKGllsA==} + engines: {node: '>=18.0.0', npm: '>=8.0.0'} + hasBin: true + + router@2.2.0: + resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==} + engines: {node: '>= 18'} + + run-applescript@7.1.0: + resolution: {integrity: sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==} + engines: {node: '>=18'} + + run-parallel@1.2.0: + resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==} + + safe-buffer@5.2.1: + resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==} + + safer-buffer@2.1.2: + resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==} + + semver@7.7.3: + resolution: {integrity: sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==} + engines: {node: '>=10'} + hasBin: true + + semver@7.7.4: + resolution: {integrity: sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==} + engines: {node: '>=10'} + hasBin: true + + send@1.2.0: + resolution: {integrity: sha512-uaW0WwXKpL9blXE2o0bRhoL2EGXIrZxQ2ZQ4mgcfoBxdFmQold+qWsD2jLrfZ0trjKL6vOw0j//eAwcALFjKSw==} + engines: {node: '>= 18'} + + serve-static@2.2.0: + resolution: {integrity: sha512-61g9pCh0Vnh7IutZjtLGGpTA355+OPn2TyDv/6ivP2h/AdAVX9azsoxmg2/M6nZeQZNYBEwIcsne1mJd9oQItQ==} + engines: {node: '>= 18'} + + setprototypeof@1.2.0: + resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==} + + shebang-command@2.0.0: + resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==} + engines: {node: '>=8'} + + shebang-regex@3.0.0: + resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==} + engines: {node: '>=8'} + + side-channel-list@1.0.0: + resolution: {integrity: sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==} + engines: {node: '>= 0.4'} + + side-channel-map@1.0.1: + resolution: {integrity: sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==} + engines: {node: '>= 0.4'} + + side-channel-weakmap@1.0.2: + resolution: {integrity: sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==} + engines: {node: '>= 0.4'} + + side-channel@1.1.0: + resolution: {integrity: sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==} + engines: {node: '>= 0.4'} + + siginfo@2.0.0: + resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==} + + signal-exit@3.0.7: + resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==} + + signal-exit@4.1.0: + resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==} + engines: {node: '>=14'} + + slash@3.0.0: + resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==} + engines: {node: '>=8'} + + source-map-js@1.2.1: + resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==} + engines: {node: '>=0.10.0'} + + source-map@0.7.6: + resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==} + engines: {node: '>= 12'} + + spawndamnit@3.0.1: + resolution: {integrity: sha512-MmnduQUuHCoFckZoWnXsTg7JaiLBJrKFj9UI2MbRPGaJeVpsLcVBu6P/IGZovziM/YBsellCmsprgNA+w0CzVg==} + + sprintf-js@1.0.3: + resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==} + + stackback@0.0.2: + resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==} + + statuses@2.0.2: + resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==} + engines: {node: '>= 0.8'} + + std-env@4.1.0: + resolution: {integrity: sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==} + + stdin-discarder@0.3.2: + resolution: {integrity: sha512-eCPu1qRxPVkl5605OTWF8Wz40b4Mf45NY5LQmVPQ599knfs5QhASUm9GbJ5BDMDOXgrnh0wyEdvzmL//YMlw0A==} + engines: {node: '>=18'} + + string-width@4.2.3: + resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==} + engines: {node: '>=8'} + + string-width@7.2.0: + resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==} + engines: {node: '>=18'} + + string-width@8.1.0: + resolution: {integrity: sha512-Kxl3KJGb/gxkaUMOjRsQ8IrXiGW75O4E3RPjFIINOVH8AMl2SQ/yWdTzWwF3FevIX9LcMAjJW+GRwAlAbTSXdg==} + engines: {node: '>=20'} + + strip-ansi@6.0.1: + resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==} + engines: {node: '>=8'} + + strip-ansi@7.1.2: + resolution: {integrity: sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==} + engines: {node: '>=12'} + + strip-bom@3.0.0: + resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==} + engines: {node: '>=4'} + + strip-json-comments@3.1.1: + resolution: {integrity: sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==} + engines: {node: '>=8'} + + strnum@2.3.0: + resolution: {integrity: sha512-ums3KNd42PGyx5xaoVTO1mjU1bH3NpY4vsrVlnv9PNGqQj8wd7rJ6nEypLrJ7z5vxK5RP0yMLo6J/Gsm62DI5Q==} + + sucrase@3.35.1: + resolution: {integrity: sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==} + engines: {node: '>=16 || 14 >=14.17'} + hasBin: true + + supports-color@7.2.0: + resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==} + engines: {node: '>=8'} + + synckit@0.11.13: + resolution: {integrity: sha512-eNRKgb3z66Yp3D2CixVujOUvXLFUTij/zVnV8KRyvFdQwpz7I5DS8UfRkTeLzb64u+dkzDSdelE24izu+zSSUg==} + engines: {node: ^14.18.0 || >=16.0.0} + + term-size@2.2.1: + resolution: {integrity: sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==} + engines: {node: '>=8'} + + thenify-all@1.6.0: + resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==} + engines: {node: '>=0.8'} + + thenify@3.3.1: + resolution: {integrity: sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==} + + tinybench@2.9.0: + resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==} + + tinyexec@0.3.2: + resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==} + + tinyexec@1.2.4: + resolution: {integrity: sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==} + engines: {node: '>=18'} + + tinyglobby@0.2.15: + resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==} + engines: {node: '>=12.0.0'} + + tinyrainbow@3.1.0: + resolution: {integrity: sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==} + engines: {node: '>=14.0.0'} + + to-regex-range@5.0.1: + resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==} + engines: {node: '>=8.0'} + + toidentifier@1.0.1: + resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==} + engines: {node: '>=0.6'} + + tree-kill@1.2.2: + resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==} + hasBin: true + + ts-algebra@2.0.0: + resolution: {integrity: sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==} + + ts-api-utils@2.1.0: + resolution: {integrity: sha512-CUgTZL1irw8u29bzrOD/nH85jqyc74D6SshFgujOIA7osm2Rz7dYH77agkx7H4FBNxDq7Cjf+IjaX/8zwFW+ZQ==} + engines: {node: '>=18.12'} + peerDependencies: + typescript: '>=4.8.4' + + ts-interface-checker@0.1.13: + resolution: {integrity: sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==} + + tslib@2.8.1: + resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==} + + tsup@8.5.1: + resolution: {integrity: sha512-xtgkqwdhpKWr3tKPmCkvYmS9xnQK3m3XgxZHwSUjvfTjp7YfXe5tT3GgWi0F2N+ZSMsOeWeZFh7ZZFg5iPhing==} + engines: {node: '>=18'} + hasBin: true + peerDependencies: + '@microsoft/api-extractor': ^7.36.0 + '@swc/core': ^1 + postcss: ^8.4.12 + typescript: '>=4.5.0' + peerDependenciesMeta: + '@microsoft/api-extractor': + optional: true + '@swc/core': + optional: true + postcss: + optional: true + typescript: + optional: true + + tsx@4.21.0: + resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==} + engines: {node: '>=18.0.0'} + hasBin: true + + type-check@0.4.0: + resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==} + engines: {node: '>= 0.8.0'} + + type-fest@4.41.0: + resolution: {integrity: sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==} + engines: {node: '>=16'} + + type-is@2.0.1: + resolution: {integrity: sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==} + engines: {node: '>= 0.6'} + + typebox@1.1.38: + resolution: {integrity: sha512-pZ0aQPmMmXoUvSbeuWf/Hzsc+avNw/Zd6VeE8CFgkVGWyuHPJvqeJJDeJqLve+K70LvjYIoleGcoJHPT17cWoA==} + + typescript-eslint@8.47.0: + resolution: {integrity: sha512-Lwe8i2XQ3WoMjua/r1PHrCTpkubPYJCAfOurtn+mtTzqB6jNd+14n9UN1bJ4s3F49x9ixAm0FLflB/JzQ57M8Q==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + eslint: ^8.57.0 || ^9.0.0 + typescript: '>=4.8.4 <6.0.0' + + typescript@5.9.3: + resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==} + engines: {node: '>=14.17'} + hasBin: true + + ufo@1.6.1: + resolution: {integrity: sha512-9a4/uxlTWJ4+a5i0ooc1rU7C7YOw3wT+UGqdeNNHWnOF9qcMBgLRS+4IYUqbczewFx4mLEig6gawh7X6mFlEkA==} + + uncrypto@0.1.3: + resolution: {integrity: sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q==} + + undici-types@6.21.0: + resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==} + + undici-types@7.16.0: + resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==} + + undici-types@7.24.6: + resolution: {integrity: sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==} + + undici@6.26.0: + resolution: {integrity: sha512-4yqz8a3n5HmGTlsbADNtr/dJlhkh/55Rq798G6ibiULcXbDtaLpTl1pvdqcbFfeoj3iSi52lePFM7h9H21cw/A==} + engines: {node: '>=18.17'} + + undici@8.3.0: + resolution: {integrity: sha512-TkUDgb6tl7KOGZ+7e8E3d2FYgUQgF6z5YypqjWmixVQSQERFcVrVg0ySADm2LVLRh5ljAaHTCR5Fmz3Q34rB7Q==} + engines: {node: '>=22.19.0'} + + universalify@0.1.2: + resolution: {integrity: sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==} + engines: {node: '>= 4.0.0'} + + unpipe@1.0.0: + resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==} + engines: {node: '>= 0.8'} + + uri-js@4.4.1: + resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==} + + vary@1.1.2: + resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==} + engines: {node: '>= 0.8'} + + vite@7.2.4: + resolution: {integrity: sha512-NL8jTlbo0Tn4dUEXEsUg8KeyG/Lkmc4Fnzb8JXN/Ykm9G4HNImjtABMJgkQoVjOBN/j2WAwDTRytdqJbZsah7w==} + engines: {node: ^20.19.0 || >=22.12.0} + hasBin: true + peerDependencies: + '@types/node': ^20.19.0 || >=22.12.0 + jiti: '>=1.21.0' + less: ^4.0.0 + lightningcss: ^1.21.0 + sass: ^1.70.0 + sass-embedded: ^1.70.0 + stylus: '>=0.54.8' + sugarss: ^5.0.0 + terser: ^5.16.0 + tsx: ^4.8.1 + yaml: ^2.4.2 + peerDependenciesMeta: + '@types/node': + optional: true + jiti: + optional: true + less: + optional: true + lightningcss: + optional: true + sass: + optional: true + sass-embedded: + optional: true + stylus: + optional: true + sugarss: + optional: true + terser: + optional: true + tsx: + optional: true + yaml: + optional: true + + vitest@4.1.9: + resolution: {integrity: sha512-nE3/LEyc0z87uHYLZebqCUOaJr2hdtuPp7BQ4BosVFnfltxgAvMG08NyrSGlPpOUWvR27c5flSmYFTNr78L9GQ==} + engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0} + hasBin: true + peerDependencies: + '@edge-runtime/vm': '*' + '@opentelemetry/api': ^1.9.0 + '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0 + '@vitest/browser-playwright': 4.1.9 + '@vitest/browser-preview': 4.1.9 + '@vitest/browser-webdriverio': 4.1.9 + '@vitest/coverage-istanbul': 4.1.9 + '@vitest/coverage-v8': 4.1.9 + '@vitest/ui': 4.1.9 + happy-dom: '*' + jsdom: '*' + vite: ^6.0.0 || ^7.0.0 || ^8.0.0 + peerDependenciesMeta: + '@edge-runtime/vm': + optional: true + '@opentelemetry/api': + optional: true + '@types/node': + optional: true + '@vitest/browser-playwright': + optional: true + '@vitest/browser-preview': + optional: true + '@vitest/browser-webdriverio': + optional: true + '@vitest/coverage-istanbul': + optional: true + '@vitest/coverage-v8': + optional: true + '@vitest/ui': + optional: true + happy-dom: + optional: true + jsdom: + optional: true + + web-streams-polyfill@3.3.3: + resolution: {integrity: sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==} + engines: {node: '>= 8'} + + which@2.0.2: + resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==} + engines: {node: '>= 8'} + hasBin: true + + why-is-node-running@2.3.0: + resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==} + engines: {node: '>=8'} + hasBin: true + + widest-line@5.0.0: + resolution: {integrity: sha512-c9bZp7b5YtRj2wOe6dlj32MK+Bx/M/d+9VB2SHM1OtsUHR0aV0tdP6DWh/iMt0kWi1t5g1Iudu6hQRNd1A4PVA==} + engines: {node: '>=18'} + + word-wrap@1.2.5: + resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==} + engines: {node: '>=0.10.0'} + + wrap-ansi@9.0.2: + resolution: {integrity: sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==} + engines: {node: '>=18'} + + wrappy@1.0.2: + resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==} + + ws@8.20.1: + resolution: {integrity: sha512-It4dO0K5v//JtTXuPkfEOaI3uUN87iYPnqo/ZzqCoG3g8uhA66QUMs/SrM0YK7/NAu+r4LMh/9dq2A7k+rHs+w==} + engines: {node: '>=10.0.0'} + peerDependencies: + bufferutil: ^4.0.1 + utf-8-validate: '>=5.0.2' + peerDependenciesMeta: + bufferutil: + optional: true + utf-8-validate: + optional: true + + wsl-utils@0.1.0: + resolution: {integrity: sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw==} + engines: {node: '>=18'} + + xml-naming@0.1.0: + resolution: {integrity: sha512-k8KO9hrMyNk6tUWqUfkTEZbezRRpONVOzUTnc97VnCvyj6Tf9lyUR9EDAIeiVLv56jsMcoXEwjW8Kv5yPY52lw==} + engines: {node: '>=16.0.0'} + + yaml@2.9.0: + resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==} + engines: {node: '>= 14.6'} + hasBin: true + + yocto-queue@0.1.0: + resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==} + engines: {node: '>=10'} + + yoctocolors@2.1.2: + resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==} + engines: {node: '>=18'} + + zod-to-json-schema@3.25.0: + resolution: {integrity: sha512-HvWtU2UG41LALjajJrML6uQejQhNJx+JBO9IflpSja4R03iNWfKXrj6W2h7ljuLyc1nKS+9yDyL/9tD1U/yBnQ==} + peerDependencies: + zod: ^3.25 || ^4 + + zod-to-json-schema@3.25.2: + resolution: {integrity: sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==} + peerDependencies: + zod: ^3.25.28 || ^4 + + zod@4.4.3: + resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==} + +snapshots: + + '@ai-sdk/amazon-bedrock@4.0.12(zod@4.4.3)': + dependencies: + '@ai-sdk/anthropic': 3.0.9(zod@4.4.3) + '@ai-sdk/provider': 3.0.2 + '@ai-sdk/provider-utils': 4.0.4(zod@4.4.3) + '@smithy/eventstream-codec': 4.2.5 + '@smithy/util-utf8': 4.2.0 + aws4fetch: 1.0.20 + zod: 4.4.3 + + '@ai-sdk/anthropic@3.0.9(zod@4.4.3)': + dependencies: + '@ai-sdk/provider': 3.0.2 + '@ai-sdk/provider-utils': 4.0.4(zod@4.4.3) + zod: 4.4.3 + + '@ai-sdk/gateway@3.0.10(zod@4.4.3)': + dependencies: + '@ai-sdk/provider': 3.0.2 + '@ai-sdk/provider-utils': 4.0.4(zod@4.4.3) + '@vercel/oidc': 3.1.0 + zod: 4.4.3 + + '@ai-sdk/provider-utils@4.0.4(zod@4.4.3)': + dependencies: + '@ai-sdk/provider': 3.0.2 + '@standard-schema/spec': 1.1.0 + eventsource-parser: 3.0.6 + zod: 4.4.3 + + '@ai-sdk/provider@3.0.2': + dependencies: + json-schema: 0.4.0 + + '@anthropic-ai/sdk@0.91.1(zod@4.4.3)': + dependencies: + json-schema-to-ts: 3.1.1 + optionalDependencies: + zod: 4.4.3 + + '@aws-crypto/crc32@5.2.0': + dependencies: + '@aws-crypto/util': 5.2.0 + '@aws-sdk/types': 3.936.0 + tslib: 2.8.1 + + '@aws-crypto/sha256-browser@5.2.0': + dependencies: + '@aws-crypto/sha256-js': 5.2.0 + '@aws-crypto/supports-web-crypto': 5.2.0 + '@aws-crypto/util': 5.2.0 + '@aws-sdk/types': 3.973.9 + '@aws-sdk/util-locate-window': 3.965.5 + '@smithy/util-utf8': 2.3.0 + tslib: 2.8.1 + + '@aws-crypto/sha256-js@5.2.0': + dependencies: + '@aws-crypto/util': 5.2.0 + '@aws-sdk/types': 3.973.9 + tslib: 2.8.1 + + '@aws-crypto/supports-web-crypto@5.2.0': + dependencies: + tslib: 2.8.1 + + '@aws-crypto/util@5.2.0': + dependencies: + '@aws-sdk/types': 3.936.0 + '@smithy/util-utf8': 2.3.0 + tslib: 2.8.1 + + '@aws-sdk/client-bedrock-runtime@3.1048.0': + dependencies: + '@aws-crypto/sha256-browser': 5.2.0 + '@aws-crypto/sha256-js': 5.2.0 + '@aws-sdk/core': 3.974.13 + '@aws-sdk/credential-provider-node': 3.972.44 + '@aws-sdk/eventstream-handler-node': 3.972.17 + '@aws-sdk/middleware-eventstream': 3.972.13 + '@aws-sdk/middleware-websocket': 3.972.21 + '@aws-sdk/token-providers': 3.1048.0 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/fetch-http-handler': 5.4.4 + '@smithy/node-http-handler': 4.7.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/core@3.974.13': + dependencies: + '@aws-sdk/types': 3.973.9 + '@aws-sdk/xml-builder': 3.972.25 + '@aws/lambda-invoke-store': 0.2.4 + '@smithy/core': 3.24.4 + '@smithy/signature-v4': 5.4.4 + '@smithy/types': 4.14.2 + bowser: 2.14.1 + tslib: 2.8.1 + + '@aws-sdk/credential-provider-env@3.972.39': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/credential-provider-http@3.972.41': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/fetch-http-handler': 5.4.4 + '@smithy/node-http-handler': 4.7.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/credential-provider-ini@3.972.43': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/credential-provider-env': 3.972.39 + '@aws-sdk/credential-provider-http': 3.972.41 + '@aws-sdk/credential-provider-login': 3.972.43 + '@aws-sdk/credential-provider-process': 3.972.39 + '@aws-sdk/credential-provider-sso': 3.972.43 + '@aws-sdk/credential-provider-web-identity': 3.972.43 + '@aws-sdk/nested-clients': 3.997.11 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/credential-provider-imds': 4.3.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/credential-provider-login@3.972.43': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/nested-clients': 3.997.11 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/credential-provider-node@3.972.44': + dependencies: + '@aws-sdk/credential-provider-env': 3.972.39 + '@aws-sdk/credential-provider-http': 3.972.41 + '@aws-sdk/credential-provider-ini': 3.972.43 + '@aws-sdk/credential-provider-process': 3.972.39 + '@aws-sdk/credential-provider-sso': 3.972.43 + '@aws-sdk/credential-provider-web-identity': 3.972.43 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/credential-provider-imds': 4.3.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/credential-provider-process@3.972.39': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/credential-provider-sso@3.972.43': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/nested-clients': 3.997.11 + '@aws-sdk/token-providers': 3.1052.0 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/credential-provider-web-identity@3.972.43': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/nested-clients': 3.997.11 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/eventstream-handler-node@3.972.17': + dependencies: + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/middleware-eventstream@3.972.13': + dependencies: + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/middleware-websocket@3.972.21': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/fetch-http-handler': 5.4.4 + '@smithy/signature-v4': 5.4.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/nested-clients@3.997.11': + dependencies: + '@aws-crypto/sha256-browser': 5.2.0 + '@aws-crypto/sha256-js': 5.2.0 + '@aws-sdk/core': 3.974.13 + '@aws-sdk/signature-v4-multi-region': 3.996.28 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/fetch-http-handler': 5.4.4 + '@smithy/node-http-handler': 4.7.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/signature-v4-multi-region@3.996.28': + dependencies: + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/signature-v4': 5.4.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/token-providers@3.1048.0': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/nested-clients': 3.997.11 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/token-providers@3.1052.0': + dependencies: + '@aws-sdk/core': 3.974.13 + '@aws-sdk/nested-clients': 3.997.11 + '@aws-sdk/types': 3.973.9 + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/types@3.936.0': + dependencies: + '@smithy/types': 4.9.0 + tslib: 2.8.1 + + '@aws-sdk/types@3.973.9': + dependencies: + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@aws-sdk/util-locate-window@3.965.5': + dependencies: + tslib: 2.8.1 + + '@aws-sdk/xml-builder@3.972.25': + dependencies: + '@nodable/entities': 2.1.0 + '@smithy/types': 4.14.2 + fast-xml-parser: 5.7.3 + tslib: 2.8.1 + + '@aws/lambda-invoke-store@0.2.4': {} + + '@babel/runtime@7.28.6': {} + + '@changesets/apply-release-plan@7.0.14': + dependencies: + '@changesets/config': 3.1.2 + '@changesets/get-version-range-type': 0.4.0 + '@changesets/git': 3.0.4 + '@changesets/should-skip-package': 0.1.2 + '@changesets/types': 6.1.0 + '@manypkg/get-packages': 1.1.3 + detect-indent: 6.1.0 + fs-extra: 7.0.1 + lodash.startcase: 4.4.0 + outdent: 0.5.0 + prettier: 2.8.8 + resolve-from: 5.0.0 + semver: 7.7.4 + + '@changesets/assemble-release-plan@6.0.9': + dependencies: + '@changesets/errors': 0.2.0 + '@changesets/get-dependents-graph': 2.1.3 + '@changesets/should-skip-package': 0.1.2 + '@changesets/types': 6.1.0 + '@manypkg/get-packages': 1.1.3 + semver: 7.7.4 + + '@changesets/changelog-git@0.2.1': + dependencies: + '@changesets/types': 6.1.0 + + '@changesets/cli@2.29.8(@types/node@25.0.3)': + dependencies: + '@changesets/apply-release-plan': 7.0.14 + '@changesets/assemble-release-plan': 6.0.9 + '@changesets/changelog-git': 0.2.1 + '@changesets/config': 3.1.2 + '@changesets/errors': 0.2.0 + '@changesets/get-dependents-graph': 2.1.3 + '@changesets/get-release-plan': 4.0.14 + '@changesets/git': 3.0.4 + '@changesets/logger': 0.1.1 + '@changesets/pre': 2.0.2 + '@changesets/read': 0.6.6 + '@changesets/should-skip-package': 0.1.2 + '@changesets/types': 6.1.0 + '@changesets/write': 0.4.0 + '@inquirer/external-editor': 1.0.3(@types/node@25.0.3) + '@manypkg/get-packages': 1.1.3 + ansi-colors: 4.1.3 + ci-info: 3.9.0 + enquirer: 2.4.1 + fs-extra: 7.0.1 + mri: 1.2.0 + p-limit: 2.3.0 + package-manager-detector: 0.2.11 + picocolors: 1.1.1 + resolve-from: 5.0.0 + semver: 7.7.4 + spawndamnit: 3.0.1 + term-size: 2.2.1 + transitivePeerDependencies: + - '@types/node' + + '@changesets/config@3.1.2': + dependencies: + '@changesets/errors': 0.2.0 + '@changesets/get-dependents-graph': 2.1.3 + '@changesets/logger': 0.1.1 + '@changesets/types': 6.1.0 + '@manypkg/get-packages': 1.1.3 + fs-extra: 7.0.1 + micromatch: 4.0.8 + + '@changesets/errors@0.2.0': + dependencies: + extendable-error: 0.1.7 + + '@changesets/get-dependents-graph@2.1.3': + dependencies: + '@changesets/types': 6.1.0 + '@manypkg/get-packages': 1.1.3 + picocolors: 1.1.1 + semver: 7.7.4 + + '@changesets/get-release-plan@4.0.14': + dependencies: + '@changesets/assemble-release-plan': 6.0.9 + '@changesets/config': 3.1.2 + '@changesets/pre': 2.0.2 + '@changesets/read': 0.6.6 + '@changesets/types': 6.1.0 + '@manypkg/get-packages': 1.1.3 + + '@changesets/get-version-range-type@0.4.0': {} + + '@changesets/git@3.0.4': + dependencies: + '@changesets/errors': 0.2.0 + '@manypkg/get-packages': 1.1.3 + is-subdir: 1.2.0 + micromatch: 4.0.8 + spawndamnit: 3.0.1 + + '@changesets/logger@0.1.1': + dependencies: + picocolors: 1.1.1 + + '@changesets/parse@0.4.2': + dependencies: + '@changesets/types': 6.1.0 + js-yaml: 4.1.1 + + '@changesets/pre@2.0.2': + dependencies: + '@changesets/errors': 0.2.0 + '@changesets/types': 6.1.0 + '@manypkg/get-packages': 1.1.3 + fs-extra: 7.0.1 + + '@changesets/read@0.6.6': + dependencies: + '@changesets/git': 3.0.4 + '@changesets/logger': 0.1.1 + '@changesets/parse': 0.4.2 + '@changesets/types': 6.1.0 + fs-extra: 7.0.1 + p-filter: 2.1.0 + picocolors: 1.1.1 + + '@changesets/should-skip-package@0.1.2': + dependencies: + '@changesets/types': 6.1.0 + '@manypkg/get-packages': 1.1.3 + + '@changesets/types@4.1.0': {} + + '@changesets/types@6.1.0': {} + + '@changesets/write@0.4.0': + dependencies: + '@changesets/types': 6.1.0 + fs-extra: 7.0.1 + human-id: 4.1.3 + prettier: 2.8.8 + + '@earendil-works/pi-agent-core@0.78.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.20.1)(zod@4.4.3)': + dependencies: + '@earendil-works/pi-ai': 0.78.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.20.1)(zod@4.4.3) + ignore: 7.0.5 + typebox: 1.1.38 + yaml: 2.9.0 + transitivePeerDependencies: + - '@modelcontextprotocol/sdk' + - bufferutil + - supports-color + - utf-8-validate + - ws + - zod + + '@earendil-works/pi-ai@0.78.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.20.1)(zod@4.4.3)': + dependencies: + '@anthropic-ai/sdk': 0.91.1(zod@4.4.3) + '@aws-sdk/client-bedrock-runtime': 3.1048.0 + '@google/genai': 1.52.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3)) + '@mistralai/mistralai': 2.2.1 + '@smithy/node-http-handler': 4.7.3 + http-proxy-agent: 7.0.2 + https-proxy-agent: 7.0.6 + openai: 6.26.0(ws@8.20.1)(zod@4.4.3) + partial-json: 0.1.7 + typebox: 1.1.38 + transitivePeerDependencies: + - '@modelcontextprotocol/sdk' + - bufferutil + - supports-color + - utf-8-validate + - ws + - zod + + '@earendil-works/pi-coding-agent@0.78.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.20.1)(zod@4.4.3)': + dependencies: + '@earendil-works/pi-agent-core': 0.78.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.20.1)(zod@4.4.3) + '@earendil-works/pi-ai': 0.78.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.20.1)(zod@4.4.3) + '@earendil-works/pi-tui': 0.78.0 + '@silvia-odwyer/photon-node': 0.3.4 + chalk: 5.6.2 + cross-spawn: 7.0.6 + diff: 8.0.4 + glob: 13.0.6 + highlight.js: 10.7.3 + hosted-git-info: 9.0.3 + ignore: 7.0.5 + jiti: 2.7.0 + minimatch: 10.2.5 + proper-lockfile: 4.1.2 + typebox: 1.1.38 + undici: 8.3.0 + yaml: 2.9.0 + optionalDependencies: + '@mariozechner/clipboard': 0.3.9 + transitivePeerDependencies: + - '@modelcontextprotocol/sdk' + - bufferutil + - supports-color + - utf-8-validate + - ws + - zod + + '@earendil-works/pi-tui@0.78.0': + dependencies: + get-east-asian-width: 1.6.0 + marked: 15.0.12 + + '@esbuild/aix-ppc64@0.25.12': + optional: true + + '@esbuild/aix-ppc64@0.27.0': + optional: true + + '@esbuild/android-arm64@0.25.12': + optional: true + + '@esbuild/android-arm64@0.27.0': + optional: true + + '@esbuild/android-arm@0.25.12': + optional: true + + '@esbuild/android-arm@0.27.0': + optional: true + + '@esbuild/android-x64@0.25.12': + optional: true + + '@esbuild/android-x64@0.27.0': + optional: true + + '@esbuild/darwin-arm64@0.25.12': + optional: true + + '@esbuild/darwin-arm64@0.27.0': + optional: true + + '@esbuild/darwin-x64@0.25.12': + optional: true + + '@esbuild/darwin-x64@0.27.0': + optional: true + + '@esbuild/freebsd-arm64@0.25.12': + optional: true + + '@esbuild/freebsd-arm64@0.27.0': + optional: true + + '@esbuild/freebsd-x64@0.25.12': + optional: true + + '@esbuild/freebsd-x64@0.27.0': + optional: true + + '@esbuild/linux-arm64@0.25.12': + optional: true + + '@esbuild/linux-arm64@0.27.0': + optional: true + + '@esbuild/linux-arm@0.25.12': + optional: true + + '@esbuild/linux-arm@0.27.0': + optional: true + + '@esbuild/linux-ia32@0.25.12': + optional: true + + '@esbuild/linux-ia32@0.27.0': + optional: true + + '@esbuild/linux-loong64@0.25.12': + optional: true + + '@esbuild/linux-loong64@0.27.0': + optional: true + + '@esbuild/linux-mips64el@0.25.12': + optional: true + + '@esbuild/linux-mips64el@0.27.0': + optional: true + + '@esbuild/linux-ppc64@0.25.12': + optional: true + + '@esbuild/linux-ppc64@0.27.0': + optional: true + + '@esbuild/linux-riscv64@0.25.12': + optional: true + + '@esbuild/linux-riscv64@0.27.0': + optional: true + + '@esbuild/linux-s390x@0.25.12': + optional: true + + '@esbuild/linux-s390x@0.27.0': + optional: true + + '@esbuild/linux-x64@0.25.12': + optional: true + + '@esbuild/linux-x64@0.27.0': + optional: true + + '@esbuild/netbsd-arm64@0.25.12': + optional: true + + '@esbuild/netbsd-arm64@0.27.0': + optional: true + + '@esbuild/netbsd-x64@0.25.12': + optional: true + + '@esbuild/netbsd-x64@0.27.0': + optional: true + + '@esbuild/openbsd-arm64@0.25.12': + optional: true + + '@esbuild/openbsd-arm64@0.27.0': + optional: true + + '@esbuild/openbsd-x64@0.25.12': + optional: true + + '@esbuild/openbsd-x64@0.27.0': + optional: true + + '@esbuild/openharmony-arm64@0.25.12': + optional: true + + '@esbuild/openharmony-arm64@0.27.0': + optional: true + + '@esbuild/sunos-x64@0.25.12': + optional: true + + '@esbuild/sunos-x64@0.27.0': + optional: true + + '@esbuild/win32-arm64@0.25.12': + optional: true + + '@esbuild/win32-arm64@0.27.0': + optional: true + + '@esbuild/win32-ia32@0.25.12': + optional: true + + '@esbuild/win32-ia32@0.27.0': + optional: true + + '@esbuild/win32-x64@0.25.12': + optional: true + + '@esbuild/win32-x64@0.27.0': + optional: true + + '@eslint-community/eslint-utils@4.9.0(eslint@9.39.4(jiti@2.7.0))': + dependencies: + eslint: 9.39.4(jiti@2.7.0) + eslint-visitor-keys: 3.4.3 + + '@eslint-community/regexpp@4.12.2': {} + + '@eslint/config-array@0.21.2': + dependencies: + '@eslint/object-schema': 2.1.7 + debug: 4.4.3 + minimatch: 3.1.5 + transitivePeerDependencies: + - supports-color + + '@eslint/config-helpers@0.4.2': + dependencies: + '@eslint/core': 0.17.0 + + '@eslint/core@0.17.0': + dependencies: + '@types/json-schema': 7.0.15 + + '@eslint/eslintrc@3.3.5': + dependencies: + ajv: 6.15.0 + debug: 4.4.3 + espree: 10.4.0 + globals: 14.0.0 + ignore: 5.3.2 + import-fresh: 3.3.1 + js-yaml: 4.1.1 + minimatch: 3.1.5 + strip-json-comments: 3.1.1 + transitivePeerDependencies: + - supports-color + + '@eslint/js@9.39.4': {} + + '@eslint/object-schema@2.1.7': {} + + '@eslint/plugin-kit@0.4.1': + dependencies: + '@eslint/core': 0.17.0 + levn: 0.4.1 + + '@google/genai@1.52.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))': + dependencies: + google-auth-library: 10.6.2 + p-retry: 4.6.2 + protobufjs: 7.6.1 + ws: 8.20.1 + optionalDependencies: + '@modelcontextprotocol/sdk': 1.29.0(zod@4.4.3) + transitivePeerDependencies: + - bufferutil + - supports-color + - utf-8-validate + + '@hono/node-server@1.19.14(hono@4.12.23)': + dependencies: + hono: 4.12.23 + + '@humanfs/core@0.19.1': {} + + '@humanfs/node@0.16.7': + dependencies: + '@humanfs/core': 0.19.1 + '@humanwhocodes/retry': 0.4.3 + + '@humanwhocodes/module-importer@1.0.1': {} + + '@humanwhocodes/retry@0.4.3': {} + + '@inquirer/ansi@2.0.3': {} + + '@inquirer/checkbox@5.0.4(@types/node@22.19.7)': + dependencies: + '@inquirer/ansi': 2.0.3 + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/figures': 2.0.3 + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/confirm@6.0.4(@types/node@22.19.7)': + dependencies: + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/core@11.1.1(@types/node@22.19.7)': + dependencies: + '@inquirer/ansi': 2.0.3 + '@inquirer/figures': 2.0.3 + '@inquirer/type': 4.0.3(@types/node@22.19.7) + cli-width: 4.1.0 + mute-stream: 3.0.0 + signal-exit: 4.1.0 + wrap-ansi: 9.0.2 + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/core@11.1.1(@types/node@25.0.3)': + dependencies: + '@inquirer/ansi': 2.0.3 + '@inquirer/figures': 2.0.3 + '@inquirer/type': 4.0.3(@types/node@25.0.3) + cli-width: 4.1.0 + mute-stream: 3.0.0 + signal-exit: 4.1.0 + wrap-ansi: 9.0.2 + optionalDependencies: + '@types/node': 25.0.3 + + '@inquirer/editor@5.0.4(@types/node@22.19.7)': + dependencies: + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/external-editor': 2.0.3(@types/node@22.19.7) + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/expand@5.0.4(@types/node@22.19.7)': + dependencies: + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/external-editor@1.0.3(@types/node@25.0.3)': + dependencies: + chardet: 2.1.1 + iconv-lite: 0.7.2 + optionalDependencies: + '@types/node': 25.0.3 + + '@inquirer/external-editor@2.0.3(@types/node@22.19.7)': + dependencies: + chardet: 2.1.1 + iconv-lite: 0.7.2 + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/figures@2.0.3': {} + + '@inquirer/input@5.0.4(@types/node@22.19.7)': + dependencies: + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/number@4.0.4(@types/node@22.19.7)': + dependencies: + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/password@5.0.4(@types/node@22.19.7)': + dependencies: + '@inquirer/ansi': 2.0.3 + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/prompts@8.2.0(@types/node@22.19.7)': + dependencies: + '@inquirer/checkbox': 5.0.4(@types/node@22.19.7) + '@inquirer/confirm': 6.0.4(@types/node@22.19.7) + '@inquirer/editor': 5.0.4(@types/node@22.19.7) + '@inquirer/expand': 5.0.4(@types/node@22.19.7) + '@inquirer/input': 5.0.4(@types/node@22.19.7) + '@inquirer/number': 4.0.4(@types/node@22.19.7) + '@inquirer/password': 5.0.4(@types/node@22.19.7) + '@inquirer/rawlist': 5.2.0(@types/node@22.19.7) + '@inquirer/search': 4.1.0(@types/node@22.19.7) + '@inquirer/select': 5.0.4(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/rawlist@5.2.0(@types/node@22.19.7)': + dependencies: + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/search@4.1.0(@types/node@22.19.7)': + dependencies: + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/figures': 2.0.3 + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/select@5.0.4(@types/node@22.19.7)': + dependencies: + '@inquirer/ansi': 2.0.3 + '@inquirer/core': 11.1.1(@types/node@22.19.7) + '@inquirer/figures': 2.0.3 + '@inquirer/type': 4.0.3(@types/node@22.19.7) + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/type@4.0.3(@types/node@22.19.7)': + optionalDependencies: + '@types/node': 22.19.7 + + '@inquirer/type@4.0.3(@types/node@25.0.3)': + optionalDependencies: + '@types/node': 25.0.3 + + '@jridgewell/gen-mapping@0.3.13': + dependencies: + '@jridgewell/sourcemap-codec': 1.5.5 + '@jridgewell/trace-mapping': 0.3.31 + + '@jridgewell/resolve-uri@3.1.2': {} + + '@jridgewell/sourcemap-codec@1.5.5': {} + + '@jridgewell/trace-mapping@0.3.31': + dependencies: + '@jridgewell/resolve-uri': 3.1.2 + '@jridgewell/sourcemap-codec': 1.5.5 + + '@manypkg/find-root@1.1.0': + dependencies: + '@babel/runtime': 7.28.6 + '@types/node': 12.20.55 + find-up: 4.1.0 + fs-extra: 8.1.0 + + '@manypkg/get-packages@1.1.3': + dependencies: + '@babel/runtime': 7.28.6 + '@changesets/types': 4.1.0 + '@manypkg/find-root': 1.1.0 + fs-extra: 8.1.0 + globby: 11.1.0 + read-yaml-file: 1.1.0 + + '@mariozechner/clipboard-darwin-arm64@0.3.9': + optional: true + + '@mariozechner/clipboard-darwin-universal@0.3.9': + optional: true + + '@mariozechner/clipboard-darwin-x64@0.3.9': + optional: true + + '@mariozechner/clipboard-linux-arm64-gnu@0.3.9': + optional: true + + '@mariozechner/clipboard-linux-arm64-musl@0.3.9': + optional: true + + '@mariozechner/clipboard-linux-riscv64-gnu@0.3.9': + optional: true + + '@mariozechner/clipboard-linux-x64-gnu@0.3.9': + optional: true + + '@mariozechner/clipboard-linux-x64-musl@0.3.9': + optional: true + + '@mariozechner/clipboard-win32-arm64-msvc@0.3.9': + optional: true + + '@mariozechner/clipboard-win32-x64-msvc@0.3.9': + optional: true + + '@mariozechner/clipboard@0.3.9': + optionalDependencies: + '@mariozechner/clipboard-darwin-arm64': 0.3.9 + '@mariozechner/clipboard-darwin-universal': 0.3.9 + '@mariozechner/clipboard-darwin-x64': 0.3.9 + '@mariozechner/clipboard-linux-arm64-gnu': 0.3.9 + '@mariozechner/clipboard-linux-arm64-musl': 0.3.9 + '@mariozechner/clipboard-linux-riscv64-gnu': 0.3.9 + '@mariozechner/clipboard-linux-x64-gnu': 0.3.9 + '@mariozechner/clipboard-linux-x64-musl': 0.3.9 + '@mariozechner/clipboard-win32-arm64-msvc': 0.3.9 + '@mariozechner/clipboard-win32-x64-msvc': 0.3.9 + optional: true + + '@mistralai/mistralai@2.2.1': + dependencies: + ws: 8.20.1 + zod: 4.4.3 + zod-to-json-schema: 3.25.0(zod@4.4.3) + transitivePeerDependencies: + - bufferutil + - utf-8-validate + + '@modelcontextprotocol/sdk@1.29.0(zod@4.4.3)': + dependencies: + '@hono/node-server': 1.19.14(hono@4.12.23) + ajv: 8.17.1 + ajv-formats: 3.0.1(ajv@8.17.1) + content-type: 1.0.5 + cors: 2.8.5 + cross-spawn: 7.0.6 + eventsource: 3.0.7 + eventsource-parser: 3.0.6 + express: 5.2.1 + express-rate-limit: 8.5.2(express@5.2.1) + hono: 4.12.23 + jose: 6.2.3 + json-schema-typed: 8.0.2 + pkce-challenge: 5.0.0 + raw-body: 3.0.2 + zod: 4.4.3 + zod-to-json-schema: 3.25.2(zod@4.4.3) + transitivePeerDependencies: + - supports-color + + '@nodable/entities@2.1.0': {} + + '@nodelib/fs.scandir@2.1.5': + dependencies: + '@nodelib/fs.stat': 2.0.5 + run-parallel: 1.2.0 + + '@nodelib/fs.stat@2.0.5': {} + + '@nodelib/fs.walk@1.2.8': + dependencies: + '@nodelib/fs.scandir': 2.1.5 + fastq: 1.19.1 + + '@opentelemetry/api@1.9.0': {} + + '@pkgr/core@0.3.6': {} + + '@protobufjs/aspromise@1.1.2': {} + + '@protobufjs/base64@1.1.2': {} + + '@protobufjs/codegen@2.0.5': {} + + '@protobufjs/eventemitter@1.1.1': {} + + '@protobufjs/fetch@1.1.1': + dependencies: + '@protobufjs/aspromise': 1.1.2 + + '@protobufjs/float@1.0.2': {} + + '@protobufjs/inquire@1.1.2': {} + + '@protobufjs/path@1.1.2': {} + + '@protobufjs/pool@1.1.0': {} + + '@protobufjs/utf8@1.1.1': {} + + '@rollup/rollup-android-arm-eabi@4.53.3': + optional: true + + '@rollup/rollup-android-arm64@4.53.3': + optional: true + + '@rollup/rollup-darwin-arm64@4.53.3': + optional: true + + '@rollup/rollup-darwin-x64@4.53.3': + optional: true + + '@rollup/rollup-freebsd-arm64@4.53.3': + optional: true + + '@rollup/rollup-freebsd-x64@4.53.3': + optional: true + + '@rollup/rollup-linux-arm-gnueabihf@4.53.3': + optional: true + + '@rollup/rollup-linux-arm-musleabihf@4.53.3': + optional: true + + '@rollup/rollup-linux-arm64-gnu@4.53.3': + optional: true + + '@rollup/rollup-linux-arm64-musl@4.53.3': + optional: true + + '@rollup/rollup-linux-loong64-gnu@4.53.3': + optional: true + + '@rollup/rollup-linux-ppc64-gnu@4.53.3': + optional: true + + '@rollup/rollup-linux-riscv64-gnu@4.53.3': + optional: true + + '@rollup/rollup-linux-riscv64-musl@4.53.3': + optional: true + + '@rollup/rollup-linux-s390x-gnu@4.53.3': + optional: true + + '@rollup/rollup-linux-x64-gnu@4.53.3': + optional: true + + '@rollup/rollup-linux-x64-musl@4.53.3': + optional: true + + '@rollup/rollup-openharmony-arm64@4.53.3': + optional: true + + '@rollup/rollup-win32-arm64-msvc@4.53.3': + optional: true + + '@rollup/rollup-win32-ia32-msvc@4.53.3': + optional: true + + '@rollup/rollup-win32-x64-gnu@4.53.3': + optional: true + + '@rollup/rollup-win32-x64-msvc@4.53.3': + optional: true + + '@silvia-odwyer/photon-node@0.3.4': {} + + '@smithy/core@3.24.4': + dependencies: + '@aws-crypto/crc32': 5.2.0 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@smithy/credential-provider-imds@4.3.4': + dependencies: + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@smithy/eventstream-codec@4.2.5': + dependencies: + '@aws-crypto/crc32': 5.2.0 + '@smithy/types': 4.9.0 + '@smithy/util-hex-encoding': 4.2.0 + tslib: 2.8.1 + + '@smithy/fetch-http-handler@5.4.4': + dependencies: + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@smithy/is-array-buffer@2.2.0': + dependencies: + tslib: 2.8.1 + + '@smithy/is-array-buffer@4.2.0': + dependencies: + tslib: 2.8.1 + + '@smithy/node-http-handler@4.7.3': + dependencies: + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@smithy/node-http-handler@4.7.4': + dependencies: + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@smithy/signature-v4@5.4.4': + dependencies: + '@smithy/core': 3.24.4 + '@smithy/types': 4.14.2 + tslib: 2.8.1 + + '@smithy/types@4.14.2': + dependencies: + tslib: 2.8.1 + + '@smithy/types@4.9.0': + dependencies: + tslib: 2.8.1 + + '@smithy/util-buffer-from@2.2.0': + dependencies: + '@smithy/is-array-buffer': 2.2.0 + tslib: 2.8.1 + + '@smithy/util-buffer-from@4.2.0': + dependencies: + '@smithy/is-array-buffer': 4.2.0 + tslib: 2.8.1 + + '@smithy/util-hex-encoding@4.2.0': + dependencies: + tslib: 2.8.1 + + '@smithy/util-utf8@2.3.0': + dependencies: + '@smithy/util-buffer-from': 2.2.0 + tslib: 2.8.1 + + '@smithy/util-utf8@4.2.0': + dependencies: + '@smithy/util-buffer-from': 4.2.0 + tslib: 2.8.1 + + '@standard-schema/spec@1.1.0': {} + + '@types/body-parser@1.19.6': + dependencies: + '@types/connect': 3.4.38 + '@types/node': 25.9.1 + + '@types/chai@5.2.3': + dependencies: + '@types/deep-eql': 4.0.2 + assertion-error: 2.0.1 + + '@types/connect@3.4.38': + dependencies: + '@types/node': 25.9.1 + + '@types/deep-eql@4.0.2': {} + + '@types/estree@1.0.8': {} + + '@types/express-serve-static-core@5.1.0': + dependencies: + '@types/node': 25.9.1 + '@types/qs': 6.14.0 + '@types/range-parser': 1.2.7 + '@types/send': 1.2.1 + + '@types/express@5.0.5': + dependencies: + '@types/body-parser': 1.19.6 + '@types/express-serve-static-core': 5.1.0 + '@types/serve-static': 1.15.10 + + '@types/figlet@1.7.0': {} + + '@types/http-errors@2.0.5': {} + + '@types/json-schema@7.0.15': {} + + '@types/mime@1.3.5': {} + + '@types/node@12.20.55': {} + + '@types/node@22.19.7': + dependencies: + undici-types: 6.21.0 + + '@types/node@25.0.3': + dependencies: + undici-types: 7.16.0 + + '@types/node@25.9.1': + dependencies: + undici-types: 7.24.6 + + '@types/qs@6.14.0': {} + + '@types/range-parser@1.2.7': {} + + '@types/retry@0.12.0': {} + + '@types/send@0.17.6': + dependencies: + '@types/mime': 1.3.5 + '@types/node': 25.9.1 + + '@types/send@1.2.1': + dependencies: + '@types/node': 25.9.1 + + '@types/serve-static@1.15.10': + dependencies: + '@types/http-errors': 2.0.5 + '@types/node': 25.9.1 + '@types/send': 0.17.6 + + '@typescript-eslint/eslint-plugin@8.47.0(@typescript-eslint/parser@8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3)': + dependencies: + '@eslint-community/regexpp': 4.12.2 + '@typescript-eslint/parser': 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + '@typescript-eslint/scope-manager': 8.47.0 + '@typescript-eslint/type-utils': 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + '@typescript-eslint/utils': 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + '@typescript-eslint/visitor-keys': 8.47.0 + eslint: 9.39.4(jiti@2.7.0) + graphemer: 1.4.0 + ignore: 7.0.5 + natural-compare: 1.4.0 + ts-api-utils: 2.1.0(typescript@5.9.3) + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + + '@typescript-eslint/parser@8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3)': + dependencies: + '@typescript-eslint/scope-manager': 8.47.0 + '@typescript-eslint/types': 8.47.0 + '@typescript-eslint/typescript-estree': 8.47.0(typescript@5.9.3) + '@typescript-eslint/visitor-keys': 8.47.0 + debug: 4.4.3 + eslint: 9.39.4(jiti@2.7.0) + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + + '@typescript-eslint/project-service@8.47.0(typescript@5.9.3)': + dependencies: + '@typescript-eslint/tsconfig-utils': 8.47.0(typescript@5.9.3) + '@typescript-eslint/types': 8.47.0 + debug: 4.4.3 + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + + '@typescript-eslint/scope-manager@8.47.0': + dependencies: + '@typescript-eslint/types': 8.47.0 + '@typescript-eslint/visitor-keys': 8.47.0 + + '@typescript-eslint/tsconfig-utils@8.47.0(typescript@5.9.3)': + dependencies: + typescript: 5.9.3 + + '@typescript-eslint/type-utils@8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3)': + dependencies: + '@typescript-eslint/types': 8.47.0 + '@typescript-eslint/typescript-estree': 8.47.0(typescript@5.9.3) + '@typescript-eslint/utils': 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + debug: 4.4.3 + eslint: 9.39.4(jiti@2.7.0) + ts-api-utils: 2.1.0(typescript@5.9.3) + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + + '@typescript-eslint/types@8.47.0': {} + + '@typescript-eslint/typescript-estree@8.47.0(typescript@5.9.3)': + dependencies: + '@typescript-eslint/project-service': 8.47.0(typescript@5.9.3) + '@typescript-eslint/tsconfig-utils': 8.47.0(typescript@5.9.3) + '@typescript-eslint/types': 8.47.0 + '@typescript-eslint/visitor-keys': 8.47.0 + debug: 4.4.3 + fast-glob: 3.3.3 + is-glob: 4.0.3 + minimatch: 9.0.5 + semver: 7.7.3 + ts-api-utils: 2.1.0(typescript@5.9.3) + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + + '@typescript-eslint/utils@8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3)': + dependencies: + '@eslint-community/eslint-utils': 4.9.0(eslint@9.39.4(jiti@2.7.0)) + '@typescript-eslint/scope-manager': 8.47.0 + '@typescript-eslint/types': 8.47.0 + '@typescript-eslint/typescript-estree': 8.47.0(typescript@5.9.3) + eslint: 9.39.4(jiti@2.7.0) + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + + '@typescript-eslint/visitor-keys@8.47.0': + dependencies: + '@typescript-eslint/types': 8.47.0 + eslint-visitor-keys: 4.2.1 + + '@upstash/redis@1.38.0': + dependencies: + uncrypto: 0.1.3 + + '@vercel/oidc@3.1.0': {} + + '@vitest/expect@4.1.9': + dependencies: + '@standard-schema/spec': 1.1.0 + '@types/chai': 5.2.3 + '@vitest/spy': 4.1.9 + '@vitest/utils': 4.1.9 + chai: 6.2.2 + tinyrainbow: 3.1.0 + + '@vitest/mocker@4.1.9(vite@7.2.4(@types/node@22.19.7)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0))': + dependencies: + '@vitest/spy': 4.1.9 + estree-walker: 3.0.3 + magic-string: 0.30.21 + optionalDependencies: + vite: 7.2.4(@types/node@22.19.7)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0) + + '@vitest/mocker@4.1.9(vite@7.2.4(@types/node@25.0.3)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0))': + dependencies: + '@vitest/spy': 4.1.9 + estree-walker: 3.0.3 + magic-string: 0.30.21 + optionalDependencies: + vite: 7.2.4(@types/node@25.0.3)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0) + + '@vitest/mocker@4.1.9(vite@7.2.4(@types/node@25.9.1)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0))': + dependencies: + '@vitest/spy': 4.1.9 + estree-walker: 3.0.3 + magic-string: 0.30.21 + optionalDependencies: + vite: 7.2.4(@types/node@25.9.1)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0) + + '@vitest/pretty-format@4.1.9': + dependencies: + tinyrainbow: 3.1.0 + + '@vitest/runner@4.1.9': + dependencies: + '@vitest/utils': 4.1.9 + pathe: 2.0.3 + + '@vitest/snapshot@4.1.9': + dependencies: + '@vitest/pretty-format': 4.1.9 + '@vitest/utils': 4.1.9 + magic-string: 0.30.21 + pathe: 2.0.3 + + '@vitest/spy@4.1.9': {} + + '@vitest/utils@4.1.9': + dependencies: + '@vitest/pretty-format': 4.1.9 + convert-source-map: 2.0.0 + tinyrainbow: 3.1.0 + + accepts@2.0.0: + dependencies: + mime-types: 3.0.2 + negotiator: 1.0.0 + + acorn-jsx@5.3.2(acorn@8.16.0): + dependencies: + acorn: 8.16.0 + + acorn@8.15.0: {} + + acorn@8.16.0: {} + + agent-base@7.1.4: {} + + ai@6.0.23(zod@4.4.3): + dependencies: + '@ai-sdk/gateway': 3.0.10(zod@4.4.3) + '@ai-sdk/provider': 3.0.2 + '@ai-sdk/provider-utils': 4.0.4(zod@4.4.3) + '@opentelemetry/api': 1.9.0 + zod: 4.4.3 + + ajv-formats@3.0.1(ajv@8.17.1): + optionalDependencies: + ajv: 8.17.1 + + ajv@6.15.0: + dependencies: + fast-deep-equal: 3.1.3 + fast-json-stable-stringify: 2.1.0 + json-schema-traverse: 0.4.1 + uri-js: 4.4.1 + + ajv@8.17.1: + dependencies: + fast-deep-equal: 3.1.3 + fast-uri: 3.1.0 + json-schema-traverse: 1.0.0 + require-from-string: 2.0.2 + + ansi-align@3.0.1: + dependencies: + string-width: 4.2.3 + + ansi-colors@4.1.3: {} + + ansi-regex@5.0.1: {} + + ansi-regex@6.2.2: {} + + ansi-styles@4.3.0: + dependencies: + color-convert: 2.0.1 + + ansi-styles@6.2.3: {} + + any-promise@1.3.0: {} + + argparse@1.0.10: + dependencies: + sprintf-js: 1.0.3 + + argparse@2.0.1: {} + + array-union@2.1.0: {} + + assertion-error@2.0.1: {} + + aws4fetch@1.0.20: {} + + balanced-match@1.0.2: {} + + balanced-match@4.0.4: {} + + base64-js@1.5.1: {} + + better-path-resolve@1.0.0: + dependencies: + is-windows: 1.0.2 + + bignumber.js@9.3.1: {} + + body-parser@2.2.0: + dependencies: + bytes: 3.1.2 + content-type: 1.0.5 + debug: 4.4.3 + http-errors: 2.0.1 + iconv-lite: 0.6.3 + on-finished: 2.4.1 + qs: 6.14.0 + raw-body: 3.0.2 + type-is: 2.0.1 + transitivePeerDependencies: + - supports-color + + body-parser@2.2.2: + dependencies: + bytes: 3.1.2 + content-type: 1.0.5 + debug: 4.4.3 + http-errors: 2.0.1 + iconv-lite: 0.7.2 + on-finished: 2.4.1 + qs: 6.15.2 + raw-body: 3.0.2 + type-is: 2.0.1 + transitivePeerDependencies: + - supports-color + + bowser@2.14.1: {} + + boxen@8.0.1: + dependencies: + ansi-align: 3.0.1 + camelcase: 8.0.0 + chalk: 5.6.2 + cli-boxes: 3.0.0 + string-width: 7.2.0 + type-fest: 4.41.0 + widest-line: 5.0.0 + wrap-ansi: 9.0.2 + + brace-expansion@1.1.15: + dependencies: + balanced-match: 1.0.2 + concat-map: 0.0.1 + + brace-expansion@2.0.2: + dependencies: + balanced-match: 1.0.2 + + brace-expansion@5.0.6: + dependencies: + balanced-match: 4.0.4 + + braces@3.0.3: + dependencies: + fill-range: 7.1.1 + + buffer-equal-constant-time@1.0.1: {} + + bundle-name@4.1.0: + dependencies: + run-applescript: 7.1.0 + + bundle-require@5.1.0(esbuild@0.27.0): + dependencies: + esbuild: 0.27.0 + load-tsconfig: 0.2.5 + + bytes@3.1.2: {} + + cac@6.7.14: {} + + call-bind-apply-helpers@1.0.2: + dependencies: + es-errors: 1.3.0 + function-bind: 1.1.2 + + call-bound@1.0.4: + dependencies: + call-bind-apply-helpers: 1.0.2 + get-intrinsic: 1.3.0 + + callsites@3.1.0: {} + + camelcase@8.0.0: {} + + chai@6.2.2: {} + + chalk@4.1.2: + dependencies: + ansi-styles: 4.3.0 + supports-color: 7.2.0 + + chalk@5.6.2: {} + + chardet@2.1.1: {} + + chokidar@4.0.3: + dependencies: + readdirp: 4.1.2 + + ci-info@3.9.0: {} + + cli-boxes@3.0.0: {} + + cli-cursor@5.0.0: + dependencies: + restore-cursor: 5.1.0 + + cli-spinners@3.4.0: {} + + cli-width@4.1.0: {} + + color-convert@2.0.1: + dependencies: + color-name: 1.1.4 + + color-name@1.1.4: {} + + commander@13.1.0: {} + + commander@14.0.2: {} + + commander@15.0.0: {} + + commander@4.1.1: {} + + concat-map@0.0.1: {} + + confbox@0.1.8: {} + + consola@3.4.2: {} + + content-disposition@1.0.1: {} + + content-type@1.0.5: {} + + convert-source-map@2.0.0: {} + + cookie-signature@1.2.2: {} + + cookie@0.7.2: {} + + cors@2.8.5: + dependencies: + object-assign: 4.1.1 + vary: 1.1.2 + + cross-spawn@7.0.6: + dependencies: + path-key: 3.1.1 + shebang-command: 2.0.0 + which: 2.0.2 + + data-uri-to-buffer@4.0.1: {} + + debug@4.4.3: + dependencies: + ms: 2.1.3 + + deep-is@0.1.4: {} + + default-browser-id@5.0.1: {} + + default-browser@5.4.0: + dependencies: + bundle-name: 4.1.0 + default-browser-id: 5.0.1 + + define-lazy-prop@3.0.0: {} + + depd@2.0.0: {} + + detect-indent@6.1.0: {} + + diff@8.0.4: {} + + dir-glob@3.0.1: + dependencies: + path-type: 4.0.0 + + dotenv@17.4.2: {} + + dunder-proto@1.0.1: + dependencies: + call-bind-apply-helpers: 1.0.2 + es-errors: 1.3.0 + gopd: 1.2.0 + + ecdsa-sig-formatter@1.0.11: + dependencies: + safe-buffer: 5.2.1 + + ee-first@1.1.1: {} + + emoji-regex@10.6.0: {} + + emoji-regex@8.0.0: {} + + encodeurl@2.0.0: {} + + enquirer@2.4.1: + dependencies: + ansi-colors: 4.1.3 + strip-ansi: 6.0.1 + + es-define-property@1.0.1: {} + + es-errors@1.3.0: {} + + es-module-lexer@2.3.0: {} + + es-object-atoms@1.1.1: + dependencies: + es-errors: 1.3.0 + + esbuild@0.25.12: + optionalDependencies: + '@esbuild/aix-ppc64': 0.25.12 + '@esbuild/android-arm': 0.25.12 + '@esbuild/android-arm64': 0.25.12 + '@esbuild/android-x64': 0.25.12 + '@esbuild/darwin-arm64': 0.25.12 + '@esbuild/darwin-x64': 0.25.12 + '@esbuild/freebsd-arm64': 0.25.12 + '@esbuild/freebsd-x64': 0.25.12 + '@esbuild/linux-arm': 0.25.12 + '@esbuild/linux-arm64': 0.25.12 + '@esbuild/linux-ia32': 0.25.12 + '@esbuild/linux-loong64': 0.25.12 + '@esbuild/linux-mips64el': 0.25.12 + '@esbuild/linux-ppc64': 0.25.12 + '@esbuild/linux-riscv64': 0.25.12 + '@esbuild/linux-s390x': 0.25.12 + '@esbuild/linux-x64': 0.25.12 + '@esbuild/netbsd-arm64': 0.25.12 + '@esbuild/netbsd-x64': 0.25.12 + '@esbuild/openbsd-arm64': 0.25.12 + '@esbuild/openbsd-x64': 0.25.12 + '@esbuild/openharmony-arm64': 0.25.12 + '@esbuild/sunos-x64': 0.25.12 + '@esbuild/win32-arm64': 0.25.12 + '@esbuild/win32-ia32': 0.25.12 + '@esbuild/win32-x64': 0.25.12 + + esbuild@0.27.0: + optionalDependencies: + '@esbuild/aix-ppc64': 0.27.0 + '@esbuild/android-arm': 0.27.0 + '@esbuild/android-arm64': 0.27.0 + '@esbuild/android-x64': 0.27.0 + '@esbuild/darwin-arm64': 0.27.0 + '@esbuild/darwin-x64': 0.27.0 + '@esbuild/freebsd-arm64': 0.27.0 + '@esbuild/freebsd-x64': 0.27.0 + '@esbuild/linux-arm': 0.27.0 + '@esbuild/linux-arm64': 0.27.0 + '@esbuild/linux-ia32': 0.27.0 + '@esbuild/linux-loong64': 0.27.0 + '@esbuild/linux-mips64el': 0.27.0 + '@esbuild/linux-ppc64': 0.27.0 + '@esbuild/linux-riscv64': 0.27.0 + '@esbuild/linux-s390x': 0.27.0 + '@esbuild/linux-x64': 0.27.0 + '@esbuild/netbsd-arm64': 0.27.0 + '@esbuild/netbsd-x64': 0.27.0 + '@esbuild/openbsd-arm64': 0.27.0 + '@esbuild/openbsd-x64': 0.27.0 + '@esbuild/openharmony-arm64': 0.27.0 + '@esbuild/sunos-x64': 0.27.0 + '@esbuild/win32-arm64': 0.27.0 + '@esbuild/win32-ia32': 0.27.0 + '@esbuild/win32-x64': 0.27.0 + + escape-html@1.0.3: {} + + escape-string-regexp@4.0.0: {} + + eslint-config-prettier@10.1.8(eslint@9.39.4(jiti@2.7.0)): + dependencies: + eslint: 9.39.4(jiti@2.7.0) + + eslint-plugin-prettier@5.5.6(eslint-config-prettier@10.1.8(eslint@9.39.4(jiti@2.7.0)))(eslint@9.39.4(jiti@2.7.0))(prettier@3.6.2): + dependencies: + eslint: 9.39.4(jiti@2.7.0) + prettier: 3.6.2 + prettier-linter-helpers: 1.0.1 + synckit: 0.11.13 + optionalDependencies: + eslint-config-prettier: 10.1.8(eslint@9.39.4(jiti@2.7.0)) + + eslint-scope@8.4.0: + dependencies: + esrecurse: 4.3.0 + estraverse: 5.3.0 + + eslint-visitor-keys@3.4.3: {} + + eslint-visitor-keys@4.2.1: {} + + eslint@9.39.4(jiti@2.7.0): + dependencies: + '@eslint-community/eslint-utils': 4.9.0(eslint@9.39.4(jiti@2.7.0)) + '@eslint-community/regexpp': 4.12.2 + '@eslint/config-array': 0.21.2 + '@eslint/config-helpers': 0.4.2 + '@eslint/core': 0.17.0 + '@eslint/eslintrc': 3.3.5 + '@eslint/js': 9.39.4 + '@eslint/plugin-kit': 0.4.1 + '@humanfs/node': 0.16.7 + '@humanwhocodes/module-importer': 1.0.1 + '@humanwhocodes/retry': 0.4.3 + '@types/estree': 1.0.8 + ajv: 6.15.0 + chalk: 4.1.2 + cross-spawn: 7.0.6 + debug: 4.4.3 + escape-string-regexp: 4.0.0 + eslint-scope: 8.4.0 + eslint-visitor-keys: 4.2.1 + espree: 10.4.0 + esquery: 1.7.0 + esutils: 2.0.3 + fast-deep-equal: 3.1.3 + file-entry-cache: 8.0.0 + find-up: 5.0.0 + glob-parent: 6.0.2 + ignore: 5.3.2 + imurmurhash: 0.1.4 + is-glob: 4.0.3 + json-stable-stringify-without-jsonify: 1.0.1 + lodash.merge: 4.6.2 + minimatch: 3.1.5 + natural-compare: 1.4.0 + optionator: 0.9.4 + optionalDependencies: + jiti: 2.7.0 + transitivePeerDependencies: + - supports-color + + espree@10.4.0: + dependencies: + acorn: 8.16.0 + acorn-jsx: 5.3.2(acorn@8.16.0) + eslint-visitor-keys: 4.2.1 + + esprima@4.0.1: {} + + esquery@1.7.0: + dependencies: + estraverse: 5.3.0 + + esrecurse@4.3.0: + dependencies: + estraverse: 5.3.0 + + estraverse@5.3.0: {} + + estree-walker@3.0.3: + dependencies: + '@types/estree': 1.0.8 + + esutils@2.0.3: {} + + etag@1.8.1: {} + + eventsource-parser@3.0.6: {} + + eventsource@3.0.7: + dependencies: + eventsource-parser: 3.0.6 + + expect-type@1.4.0: {} + + express-rate-limit@8.5.2(express@5.2.1): + dependencies: + express: 5.2.1 + ip-address: 10.2.0 + + express@5.1.0: + dependencies: + accepts: 2.0.0 + body-parser: 2.2.0 + content-disposition: 1.0.1 + content-type: 1.0.5 + cookie: 0.7.2 + cookie-signature: 1.2.2 + debug: 4.4.3 + encodeurl: 2.0.0 + escape-html: 1.0.3 + etag: 1.8.1 + finalhandler: 2.1.0 + fresh: 2.0.0 + http-errors: 2.0.1 + merge-descriptors: 2.0.0 + mime-types: 3.0.2 + on-finished: 2.4.1 + once: 1.4.0 + parseurl: 1.3.3 + proxy-addr: 2.0.7 + qs: 6.14.0 + range-parser: 1.2.1 + router: 2.2.0 + send: 1.2.0 + serve-static: 2.2.0 + statuses: 2.0.2 + type-is: 2.0.1 + vary: 1.1.2 + transitivePeerDependencies: + - supports-color + + express@5.2.1: + dependencies: + accepts: 2.0.0 + body-parser: 2.2.2 + content-disposition: 1.0.1 + content-type: 1.0.5 + cookie: 0.7.2 + cookie-signature: 1.2.2 + debug: 4.4.3 + depd: 2.0.0 + encodeurl: 2.0.0 + escape-html: 1.0.3 + etag: 1.8.1 + finalhandler: 2.1.0 + fresh: 2.0.0 + http-errors: 2.0.1 + merge-descriptors: 2.0.0 + mime-types: 3.0.2 + on-finished: 2.4.1 + once: 1.4.0 + parseurl: 1.3.3 + proxy-addr: 2.0.7 + qs: 6.14.0 + range-parser: 1.2.1 + router: 2.2.0 + send: 1.2.0 + serve-static: 2.2.0 + statuses: 2.0.2 + type-is: 2.0.1 + vary: 1.1.2 + transitivePeerDependencies: + - supports-color + + extend@3.0.2: {} + + extendable-error@0.1.7: {} + + fast-deep-equal@3.1.3: {} + + fast-diff@1.3.0: {} + + fast-glob@3.3.3: + dependencies: + '@nodelib/fs.stat': 2.0.5 + '@nodelib/fs.walk': 1.2.8 + glob-parent: 5.1.2 + merge2: 1.4.1 + micromatch: 4.0.8 + + fast-json-stable-stringify@2.1.0: {} + + fast-levenshtein@2.0.6: {} + + fast-uri@3.1.0: {} + + fast-xml-builder@1.2.0: + dependencies: + path-expression-matcher: 1.5.0 + xml-naming: 0.1.0 + + fast-xml-parser@5.7.3: + dependencies: + '@nodable/entities': 2.1.0 + fast-xml-builder: 1.2.0 + path-expression-matcher: 1.5.0 + strnum: 2.3.0 + + fastq@1.19.1: + dependencies: + reusify: 1.1.0 + + fdir@6.5.0(picomatch@4.0.3): + optionalDependencies: + picomatch: 4.0.3 + + fetch-blob@3.2.0: + dependencies: + node-domexception: 1.0.0 + web-streams-polyfill: 3.3.3 + + figlet@1.9.4: + dependencies: + commander: 14.0.2 + + file-entry-cache@8.0.0: + dependencies: + flat-cache: 4.0.1 + + fill-range@7.1.1: + dependencies: + to-regex-range: 5.0.1 + + finalhandler@2.1.0: + dependencies: + debug: 4.4.3 + encodeurl: 2.0.0 + escape-html: 1.0.3 + on-finished: 2.4.1 + parseurl: 1.3.3 + statuses: 2.0.2 + transitivePeerDependencies: + - supports-color + + find-up@4.1.0: + dependencies: + locate-path: 5.0.0 + path-exists: 4.0.0 + + find-up@5.0.0: + dependencies: + locate-path: 6.0.0 + path-exists: 4.0.0 + + fix-dts-default-cjs-exports@1.0.1: + dependencies: + magic-string: 0.30.21 + mlly: 1.8.0 + rollup: 4.53.3 + + flat-cache@4.0.1: + dependencies: + flatted: 3.3.3 + keyv: 4.5.4 + + flatted@3.3.3: {} + + formdata-polyfill@4.0.10: + dependencies: + fetch-blob: 3.2.0 + + forwarded@0.2.0: {} + + fresh@2.0.0: {} + + fs-extra@7.0.1: + dependencies: + graceful-fs: 4.2.11 + jsonfile: 4.0.0 + universalify: 0.1.2 + + fs-extra@8.1.0: + dependencies: + graceful-fs: 4.2.11 + jsonfile: 4.0.0 + universalify: 0.1.2 + + fsevents@2.3.3: + optional: true + + function-bind@1.1.2: {} + + gaxios@7.1.4: + dependencies: + extend: 3.0.2 + https-proxy-agent: 7.0.6 + node-fetch: 3.3.2 + transitivePeerDependencies: + - supports-color + + gcp-metadata@8.1.2: + dependencies: + gaxios: 7.1.4 + google-logging-utils: 1.1.3 + json-bigint: 1.0.0 + transitivePeerDependencies: + - supports-color + + get-east-asian-width@1.6.0: {} + + get-intrinsic@1.3.0: + dependencies: + call-bind-apply-helpers: 1.0.2 + es-define-property: 1.0.1 + es-errors: 1.3.0 + es-object-atoms: 1.1.1 + function-bind: 1.1.2 + get-proto: 1.0.1 + gopd: 1.2.0 + has-symbols: 1.1.0 + hasown: 2.0.2 + math-intrinsics: 1.1.0 + + get-proto@1.0.1: + dependencies: + dunder-proto: 1.0.1 + es-object-atoms: 1.1.1 + + get-tsconfig@4.14.0: + dependencies: + resolve-pkg-maps: 1.0.0 + optional: true + + glob-parent@5.1.2: + dependencies: + is-glob: 4.0.3 + + glob-parent@6.0.2: + dependencies: + is-glob: 4.0.3 + + glob@13.0.6: + dependencies: + minimatch: 10.2.5 + minipass: 7.1.3 + path-scurry: 2.0.2 + + globals@14.0.0: {} + + globby@11.1.0: + dependencies: + array-union: 2.1.0 + dir-glob: 3.0.1 + fast-glob: 3.3.3 + ignore: 5.3.2 + merge2: 1.4.1 + slash: 3.0.0 + + google-auth-library@10.6.2: + dependencies: + base64-js: 1.5.1 + ecdsa-sig-formatter: 1.0.11 + gaxios: 7.1.4 + gcp-metadata: 8.1.2 + google-logging-utils: 1.1.3 + jws: 4.0.1 + transitivePeerDependencies: + - supports-color + + google-logging-utils@1.1.3: {} + + gopd@1.2.0: {} + + graceful-fs@4.2.11: {} + + graphemer@1.4.0: {} + + has-flag@4.0.0: {} + + has-symbols@1.1.0: {} + + hasown@2.0.2: + dependencies: + function-bind: 1.1.2 + + highlight.js@10.7.3: {} + + hono@4.12.23: {} + + hosted-git-info@9.0.3: + dependencies: + lru-cache: 11.5.0 + + http-errors@2.0.1: + dependencies: + depd: 2.0.0 + inherits: 2.0.4 + setprototypeof: 1.2.0 + statuses: 2.0.2 + toidentifier: 1.0.1 + + http-proxy-agent@7.0.2: + dependencies: + agent-base: 7.1.4 + debug: 4.4.3 + transitivePeerDependencies: + - supports-color + + https-proxy-agent@7.0.6: + dependencies: + agent-base: 7.1.4 + debug: 4.4.3 + transitivePeerDependencies: + - supports-color + + human-id@4.1.3: {} + + iconv-lite@0.6.3: + dependencies: + safer-buffer: 2.1.2 + + iconv-lite@0.7.0: + dependencies: + safer-buffer: 2.1.2 + + iconv-lite@0.7.2: + dependencies: + safer-buffer: 2.1.2 + + ignore@5.3.2: {} + + ignore@7.0.5: {} + + import-fresh@3.3.1: + dependencies: + parent-module: 1.0.1 + resolve-from: 4.0.0 + + imurmurhash@0.1.4: {} + + inherits@2.0.4: {} + + ip-address@10.2.0: {} + + ipaddr.js@1.9.1: {} + + is-docker@3.0.0: {} + + is-extglob@2.1.1: {} + + is-fullwidth-code-point@3.0.0: {} + + is-glob@4.0.3: + dependencies: + is-extglob: 2.1.1 + + is-inside-container@1.0.0: + dependencies: + is-docker: 3.0.0 + + is-interactive@2.0.0: {} + + is-number@7.0.0: {} + + is-promise@4.0.0: {} + + is-subdir@1.2.0: + dependencies: + better-path-resolve: 1.0.0 + + is-unicode-supported@2.1.0: {} + + is-windows@1.0.2: {} + + is-wsl@3.1.0: + dependencies: + is-inside-container: 1.0.0 + + isexe@2.0.0: {} + + jiti@2.7.0: {} + + jose@6.2.3: {} + + joycon@3.1.1: {} + + js-yaml@3.14.2: + dependencies: + argparse: 1.0.10 + esprima: 4.0.1 + + js-yaml@4.1.1: + dependencies: + argparse: 2.0.1 + + json-bigint@1.0.0: + dependencies: + bignumber.js: 9.3.1 + + json-buffer@3.0.1: {} + + json-schema-to-ts@3.1.1: + dependencies: + '@babel/runtime': 7.28.6 + ts-algebra: 2.0.0 + + json-schema-traverse@0.4.1: {} + + json-schema-traverse@1.0.0: {} + + json-schema-typed@8.0.2: {} + + json-schema@0.4.0: {} + + json-stable-stringify-without-jsonify@1.0.1: {} + + jsonfile@4.0.0: + optionalDependencies: + graceful-fs: 4.2.11 + + jwa@2.0.1: + dependencies: + buffer-equal-constant-time: 1.0.1 + ecdsa-sig-formatter: 1.0.11 + safe-buffer: 5.2.1 + + jws@4.0.1: + dependencies: + jwa: 2.0.1 + safe-buffer: 5.2.1 + + keyv@4.5.4: + dependencies: + json-buffer: 3.0.1 + + levn@0.4.1: + dependencies: + prelude-ls: 1.2.1 + type-check: 0.4.0 + + lilconfig@3.1.3: {} + + lines-and-columns@1.2.4: {} + + load-tsconfig@0.2.5: {} + + locate-path@5.0.0: + dependencies: + p-locate: 4.1.0 + + locate-path@6.0.0: + dependencies: + p-locate: 5.0.0 + + lodash.merge@4.6.2: {} + + lodash.startcase@4.4.0: {} + + log-symbols@7.0.1: + dependencies: + is-unicode-supported: 2.1.0 + yoctocolors: 2.1.2 + + long@5.3.2: {} + + lru-cache@11.5.0: {} + + magic-string@0.30.21: + dependencies: + '@jridgewell/sourcemap-codec': 1.5.5 + + marked@15.0.12: {} + + math-intrinsics@1.1.0: {} + + media-typer@1.1.0: {} + + merge-descriptors@2.0.0: {} + + merge2@1.4.1: {} + + micromatch@4.0.8: + dependencies: + braces: 3.0.3 + picomatch: 2.3.1 + + mime-db@1.54.0: {} + + mime-types@3.0.2: + dependencies: + mime-db: 1.54.0 + + mimic-function@5.0.1: {} + + minimatch@10.2.5: + dependencies: + brace-expansion: 5.0.6 + + minimatch@3.1.5: + dependencies: + brace-expansion: 1.1.15 + + minimatch@9.0.5: + dependencies: + brace-expansion: 2.0.2 + + minipass@7.1.3: {} + + mlly@1.8.0: + dependencies: + acorn: 8.15.0 + pathe: 2.0.3 + pkg-types: 1.3.1 + ufo: 1.6.1 + + mri@1.2.0: {} + + ms@2.1.3: {} + + mute-stream@3.0.0: {} + + mz@2.7.0: + dependencies: + any-promise: 1.3.0 + object-assign: 4.1.1 + thenify-all: 1.6.0 + + nanoid@3.3.11: {} + + natural-compare@1.4.0: {} + + negotiator@1.0.0: {} + + node-domexception@1.0.0: {} + + node-fetch@3.3.2: + dependencies: + data-uri-to-buffer: 4.0.1 + fetch-blob: 3.2.0 + formdata-polyfill: 4.0.10 + + object-assign@4.1.1: {} + + object-inspect@1.13.4: {} + + obug@2.1.1: {} + + on-finished@2.4.1: + dependencies: + ee-first: 1.1.1 + + once@1.4.0: + dependencies: + wrappy: 1.0.2 + + onetime@7.0.0: + dependencies: + mimic-function: 5.0.1 + + open@10.2.0: + dependencies: + default-browser: 5.4.0 + define-lazy-prop: 3.0.0 + is-inside-container: 1.0.0 + wsl-utils: 0.1.0 + + openai@6.26.0(ws@8.20.1)(zod@4.4.3): + optionalDependencies: + ws: 8.20.1 + zod: 4.4.3 + + optionator@0.9.4: + dependencies: + deep-is: 0.1.4 + fast-levenshtein: 2.0.6 + levn: 0.4.1 + prelude-ls: 1.2.1 + type-check: 0.4.0 + word-wrap: 1.2.5 + + ora@9.4.0: + dependencies: + chalk: 5.6.2 + cli-cursor: 5.0.0 + cli-spinners: 3.4.0 + is-interactive: 2.0.0 + is-unicode-supported: 2.1.0 + log-symbols: 7.0.1 + stdin-discarder: 0.3.2 + string-width: 8.1.0 + + outdent@0.5.0: {} + + p-filter@2.1.0: + dependencies: + p-map: 2.1.0 + + p-limit@2.3.0: + dependencies: + p-try: 2.2.0 + + p-limit@3.1.0: + dependencies: + yocto-queue: 0.1.0 + + p-locate@4.1.0: + dependencies: + p-limit: 2.3.0 + + p-locate@5.0.0: + dependencies: + p-limit: 3.1.0 + + p-map@2.1.0: {} + + p-retry@4.6.2: + dependencies: + '@types/retry': 0.12.0 + retry: 0.13.1 + + p-try@2.2.0: {} + + package-manager-detector@0.2.11: + dependencies: + quansync: 0.2.11 + + parent-module@1.0.1: + dependencies: + callsites: 3.1.0 + + parseurl@1.3.3: {} + + partial-json@0.1.7: {} + + path-exists@4.0.0: {} + + path-expression-matcher@1.5.0: {} + + path-key@3.1.1: {} + + path-scurry@2.0.2: + dependencies: + lru-cache: 11.5.0 + minipass: 7.1.3 + + path-to-regexp@8.3.0: {} + + path-type@4.0.0: {} + + pathe@2.0.3: {} + + picocolors@1.1.1: {} + + picomatch@2.3.1: {} + + picomatch@4.0.3: {} + + pify@4.0.1: {} + + pirates@4.0.7: {} + + pkce-challenge@5.0.0: {} + + pkg-types@1.3.1: + dependencies: + confbox: 0.1.8 + mlly: 1.8.0 + pathe: 2.0.3 + + postcss-load-config@6.0.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.9.0): + dependencies: + lilconfig: 3.1.3 + optionalDependencies: + jiti: 2.7.0 + postcss: 8.5.6 + tsx: 4.21.0 + yaml: 2.9.0 + + postcss@8.5.6: + dependencies: + nanoid: 3.3.11 + picocolors: 1.1.1 + source-map-js: 1.2.1 + + prelude-ls@1.2.1: {} + + prettier-linter-helpers@1.0.1: + dependencies: + fast-diff: 1.3.0 + + prettier@2.8.8: {} + + prettier@3.6.2: {} + + proper-lockfile@4.1.2: + dependencies: + graceful-fs: 4.2.11 + retry: 0.12.0 + signal-exit: 3.0.7 + + protobufjs@7.6.1: + dependencies: + '@protobufjs/aspromise': 1.1.2 + '@protobufjs/base64': 1.1.2 + '@protobufjs/codegen': 2.0.5 + '@protobufjs/eventemitter': 1.1.1 + '@protobufjs/fetch': 1.1.1 + '@protobufjs/float': 1.0.2 + '@protobufjs/inquire': 1.1.2 + '@protobufjs/path': 1.1.2 + '@protobufjs/pool': 1.1.0 + '@protobufjs/utf8': 1.1.1 + '@types/node': 25.9.1 + long: 5.3.2 + + proxy-addr@2.0.7: + dependencies: + forwarded: 0.2.0 + ipaddr.js: 1.9.1 + + punycode@2.3.1: {} + + qs@6.14.0: + dependencies: + side-channel: 1.1.0 + + qs@6.15.2: + dependencies: + side-channel: 1.1.0 + + quansync@0.2.11: {} + + queue-microtask@1.2.3: {} + + range-parser@1.2.1: {} + + raw-body@3.0.2: + dependencies: + bytes: 3.1.2 + http-errors: 2.0.1 + iconv-lite: 0.7.0 + unpipe: 1.0.0 + + read-yaml-file@1.1.0: + dependencies: + graceful-fs: 4.2.11 + js-yaml: 3.14.2 + pify: 4.0.1 + strip-bom: 3.0.0 + + readdirp@4.1.2: {} + + require-from-string@2.0.2: {} + + resolve-from@4.0.0: {} + + resolve-from@5.0.0: {} + + resolve-pkg-maps@1.0.0: + optional: true + + restore-cursor@5.1.0: + dependencies: + onetime: 7.0.0 + signal-exit: 4.1.0 + + retry@0.12.0: {} + + retry@0.13.1: {} + + reusify@1.1.0: {} + + rollup@4.53.3: + dependencies: + '@types/estree': 1.0.8 + optionalDependencies: + '@rollup/rollup-android-arm-eabi': 4.53.3 + '@rollup/rollup-android-arm64': 4.53.3 + '@rollup/rollup-darwin-arm64': 4.53.3 + '@rollup/rollup-darwin-x64': 4.53.3 + '@rollup/rollup-freebsd-arm64': 4.53.3 + '@rollup/rollup-freebsd-x64': 4.53.3 + '@rollup/rollup-linux-arm-gnueabihf': 4.53.3 + '@rollup/rollup-linux-arm-musleabihf': 4.53.3 + '@rollup/rollup-linux-arm64-gnu': 4.53.3 + '@rollup/rollup-linux-arm64-musl': 4.53.3 + '@rollup/rollup-linux-loong64-gnu': 4.53.3 + '@rollup/rollup-linux-ppc64-gnu': 4.53.3 + '@rollup/rollup-linux-riscv64-gnu': 4.53.3 + '@rollup/rollup-linux-riscv64-musl': 4.53.3 + '@rollup/rollup-linux-s390x-gnu': 4.53.3 + '@rollup/rollup-linux-x64-gnu': 4.53.3 + '@rollup/rollup-linux-x64-musl': 4.53.3 + '@rollup/rollup-openharmony-arm64': 4.53.3 + '@rollup/rollup-win32-arm64-msvc': 4.53.3 + '@rollup/rollup-win32-ia32-msvc': 4.53.3 + '@rollup/rollup-win32-x64-gnu': 4.53.3 + '@rollup/rollup-win32-x64-msvc': 4.53.3 + fsevents: 2.3.3 + + router@2.2.0: + dependencies: + debug: 4.4.3 + depd: 2.0.0 + is-promise: 4.0.0 + parseurl: 1.3.3 + path-to-regexp: 8.3.0 + transitivePeerDependencies: + - supports-color + + run-applescript@7.1.0: {} + + run-parallel@1.2.0: + dependencies: + queue-microtask: 1.2.3 + + safe-buffer@5.2.1: {} + + safer-buffer@2.1.2: {} + + semver@7.7.3: {} + + semver@7.7.4: {} + + send@1.2.0: + dependencies: + debug: 4.4.3 + encodeurl: 2.0.0 + escape-html: 1.0.3 + etag: 1.8.1 + fresh: 2.0.0 + http-errors: 2.0.1 + mime-types: 3.0.2 + ms: 2.1.3 + on-finished: 2.4.1 + range-parser: 1.2.1 + statuses: 2.0.2 + transitivePeerDependencies: + - supports-color + + serve-static@2.2.0: + dependencies: + encodeurl: 2.0.0 + escape-html: 1.0.3 + parseurl: 1.3.3 + send: 1.2.0 + transitivePeerDependencies: + - supports-color + + setprototypeof@1.2.0: {} + + shebang-command@2.0.0: + dependencies: + shebang-regex: 3.0.0 + + shebang-regex@3.0.0: {} + + side-channel-list@1.0.0: + dependencies: + es-errors: 1.3.0 + object-inspect: 1.13.4 + + side-channel-map@1.0.1: + dependencies: + call-bound: 1.0.4 + es-errors: 1.3.0 + get-intrinsic: 1.3.0 + object-inspect: 1.13.4 + + side-channel-weakmap@1.0.2: + dependencies: + call-bound: 1.0.4 + es-errors: 1.3.0 + get-intrinsic: 1.3.0 + object-inspect: 1.13.4 + side-channel-map: 1.0.1 + + side-channel@1.1.0: + dependencies: + es-errors: 1.3.0 + object-inspect: 1.13.4 + side-channel-list: 1.0.0 + side-channel-map: 1.0.1 + side-channel-weakmap: 1.0.2 + + siginfo@2.0.0: {} + + signal-exit@3.0.7: {} + + signal-exit@4.1.0: {} + + slash@3.0.0: {} + + source-map-js@1.2.1: {} + + source-map@0.7.6: {} + + spawndamnit@3.0.1: + dependencies: + cross-spawn: 7.0.6 + signal-exit: 4.1.0 + + sprintf-js@1.0.3: {} + + stackback@0.0.2: {} + + statuses@2.0.2: {} + + std-env@4.1.0: {} + + stdin-discarder@0.3.2: {} + + string-width@4.2.3: + dependencies: + emoji-regex: 8.0.0 + is-fullwidth-code-point: 3.0.0 + strip-ansi: 6.0.1 + + string-width@7.2.0: + dependencies: + emoji-regex: 10.6.0 + get-east-asian-width: 1.6.0 + strip-ansi: 7.1.2 + + string-width@8.1.0: + dependencies: + get-east-asian-width: 1.6.0 + strip-ansi: 7.1.2 + + strip-ansi@6.0.1: + dependencies: + ansi-regex: 5.0.1 + + strip-ansi@7.1.2: + dependencies: + ansi-regex: 6.2.2 + + strip-bom@3.0.0: {} + + strip-json-comments@3.1.1: {} + + strnum@2.3.0: {} + + sucrase@3.35.1: + dependencies: + '@jridgewell/gen-mapping': 0.3.13 + commander: 4.1.1 + lines-and-columns: 1.2.4 + mz: 2.7.0 + pirates: 4.0.7 + tinyglobby: 0.2.15 + ts-interface-checker: 0.1.13 + + supports-color@7.2.0: + dependencies: + has-flag: 4.0.0 + + synckit@0.11.13: + dependencies: + '@pkgr/core': 0.3.6 + + term-size@2.2.1: {} + + thenify-all@1.6.0: + dependencies: + thenify: 3.3.1 + + thenify@3.3.1: + dependencies: + any-promise: 1.3.0 + + tinybench@2.9.0: {} + + tinyexec@0.3.2: {} + + tinyexec@1.2.4: {} + + tinyglobby@0.2.15: + dependencies: + fdir: 6.5.0(picomatch@4.0.3) + picomatch: 4.0.3 + + tinyrainbow@3.1.0: {} + + to-regex-range@5.0.1: + dependencies: + is-number: 7.0.0 + + toidentifier@1.0.1: {} + + tree-kill@1.2.2: {} + + ts-algebra@2.0.0: {} + + ts-api-utils@2.1.0(typescript@5.9.3): + dependencies: + typescript: 5.9.3 + + ts-interface-checker@0.1.13: {} + + tslib@2.8.1: {} + + tsup@8.5.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0): + dependencies: + bundle-require: 5.1.0(esbuild@0.27.0) + cac: 6.7.14 + chokidar: 4.0.3 + consola: 3.4.2 + debug: 4.4.3 + esbuild: 0.27.0 + fix-dts-default-cjs-exports: 1.0.1 + joycon: 3.1.1 + picocolors: 1.1.1 + postcss-load-config: 6.0.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.9.0) + resolve-from: 5.0.0 + rollup: 4.53.3 + source-map: 0.7.6 + sucrase: 3.35.1 + tinyexec: 0.3.2 + tinyglobby: 0.2.15 + tree-kill: 1.2.2 + optionalDependencies: + postcss: 8.5.6 + typescript: 5.9.3 + transitivePeerDependencies: + - jiti + - supports-color + - tsx + - yaml + + tsx@4.21.0: + dependencies: + esbuild: 0.27.0 + get-tsconfig: 4.14.0 + optionalDependencies: + fsevents: 2.3.3 + optional: true + + type-check@0.4.0: + dependencies: + prelude-ls: 1.2.1 + + type-fest@4.41.0: {} + + type-is@2.0.1: + dependencies: + content-type: 1.0.5 + media-typer: 1.1.0 + mime-types: 3.0.2 + + typebox@1.1.38: {} + + typescript-eslint@8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3): + dependencies: + '@typescript-eslint/eslint-plugin': 8.47.0(@typescript-eslint/parser@8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + '@typescript-eslint/parser': 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + '@typescript-eslint/typescript-estree': 8.47.0(typescript@5.9.3) + '@typescript-eslint/utils': 8.47.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + eslint: 9.39.4(jiti@2.7.0) + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + + typescript@5.9.3: {} + + ufo@1.6.1: {} + + uncrypto@0.1.3: {} + + undici-types@6.21.0: {} + + undici-types@7.16.0: {} + + undici-types@7.24.6: {} + + undici@6.26.0: {} + + undici@8.3.0: {} + + universalify@0.1.2: {} + + unpipe@1.0.0: {} + + uri-js@4.4.1: + dependencies: + punycode: 2.3.1 + + vary@1.1.2: {} + + vite@7.2.4(@types/node@22.19.7)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0): + dependencies: + esbuild: 0.25.12 + fdir: 6.5.0(picomatch@4.0.3) + picomatch: 4.0.3 + postcss: 8.5.6 + rollup: 4.53.3 + tinyglobby: 0.2.15 + optionalDependencies: + '@types/node': 22.19.7 + fsevents: 2.3.3 + jiti: 2.7.0 + tsx: 4.21.0 + yaml: 2.9.0 + + vite@7.2.4(@types/node@25.0.3)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0): + dependencies: + esbuild: 0.25.12 + fdir: 6.5.0(picomatch@4.0.3) + picomatch: 4.0.3 + postcss: 8.5.6 + rollup: 4.53.3 + tinyglobby: 0.2.15 + optionalDependencies: + '@types/node': 25.0.3 + fsevents: 2.3.3 + jiti: 2.7.0 + tsx: 4.21.0 + yaml: 2.9.0 + + vite@7.2.4(@types/node@25.9.1)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0): + dependencies: + esbuild: 0.25.12 + fdir: 6.5.0(picomatch@4.0.3) + picomatch: 4.0.3 + postcss: 8.5.6 + rollup: 4.53.3 + tinyglobby: 0.2.15 + optionalDependencies: + '@types/node': 25.9.1 + fsevents: 2.3.3 + jiti: 2.7.0 + tsx: 4.21.0 + yaml: 2.9.0 + + vitest@4.1.9(@opentelemetry/api@1.9.0)(@types/node@22.19.7)(vite@7.2.4(@types/node@22.19.7)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)): + dependencies: + '@vitest/expect': 4.1.9 + '@vitest/mocker': 4.1.9(vite@7.2.4(@types/node@22.19.7)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)) + '@vitest/pretty-format': 4.1.9 + '@vitest/runner': 4.1.9 + '@vitest/snapshot': 4.1.9 + '@vitest/spy': 4.1.9 + '@vitest/utils': 4.1.9 + es-module-lexer: 2.3.0 + expect-type: 1.4.0 + magic-string: 0.30.21 + obug: 2.1.1 + pathe: 2.0.3 + picomatch: 4.0.3 + std-env: 4.1.0 + tinybench: 2.9.0 + tinyexec: 1.2.4 + tinyglobby: 0.2.15 + tinyrainbow: 3.1.0 + vite: 7.2.4(@types/node@22.19.7)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0) + why-is-node-running: 2.3.0 + optionalDependencies: + '@opentelemetry/api': 1.9.0 + '@types/node': 22.19.7 + transitivePeerDependencies: + - msw + + vitest@4.1.9(@opentelemetry/api@1.9.0)(@types/node@25.0.3)(vite@7.2.4(@types/node@25.0.3)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)): + dependencies: + '@vitest/expect': 4.1.9 + '@vitest/mocker': 4.1.9(vite@7.2.4(@types/node@25.0.3)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)) + '@vitest/pretty-format': 4.1.9 + '@vitest/runner': 4.1.9 + '@vitest/snapshot': 4.1.9 + '@vitest/spy': 4.1.9 + '@vitest/utils': 4.1.9 + es-module-lexer: 2.3.0 + expect-type: 1.4.0 + magic-string: 0.30.21 + obug: 2.1.1 + pathe: 2.0.3 + picomatch: 4.0.3 + std-env: 4.1.0 + tinybench: 2.9.0 + tinyexec: 1.2.4 + tinyglobby: 0.2.15 + tinyrainbow: 3.1.0 + vite: 7.2.4(@types/node@25.0.3)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0) + why-is-node-running: 2.3.0 + optionalDependencies: + '@opentelemetry/api': 1.9.0 + '@types/node': 25.0.3 + transitivePeerDependencies: + - msw + + vitest@4.1.9(@opentelemetry/api@1.9.0)(@types/node@25.9.1)(vite@7.2.4(@types/node@25.9.1)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)): + dependencies: + '@vitest/expect': 4.1.9 + '@vitest/mocker': 4.1.9(vite@7.2.4(@types/node@25.9.1)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0)) + '@vitest/pretty-format': 4.1.9 + '@vitest/runner': 4.1.9 + '@vitest/snapshot': 4.1.9 + '@vitest/spy': 4.1.9 + '@vitest/utils': 4.1.9 + es-module-lexer: 2.3.0 + expect-type: 1.4.0 + magic-string: 0.30.21 + obug: 2.1.1 + pathe: 2.0.3 + picomatch: 4.0.3 + std-env: 4.1.0 + tinybench: 2.9.0 + tinyexec: 1.2.4 + tinyglobby: 0.2.15 + tinyrainbow: 3.1.0 + vite: 7.2.4(@types/node@25.9.1)(jiti@2.7.0)(tsx@4.21.0)(yaml@2.9.0) + why-is-node-running: 2.3.0 + optionalDependencies: + '@opentelemetry/api': 1.9.0 + '@types/node': 25.9.1 + transitivePeerDependencies: + - msw + + web-streams-polyfill@3.3.3: {} + + which@2.0.2: + dependencies: + isexe: 2.0.0 + + why-is-node-running@2.3.0: + dependencies: + siginfo: 2.0.0 + stackback: 0.0.2 + + widest-line@5.0.0: + dependencies: + string-width: 7.2.0 + + word-wrap@1.2.5: {} + + wrap-ansi@9.0.2: + dependencies: + ansi-styles: 6.2.3 + string-width: 7.2.0 + strip-ansi: 7.1.2 + + wrappy@1.0.2: {} + + ws@8.20.1: {} + + wsl-utils@0.1.0: + dependencies: + is-wsl: 3.1.0 + + xml-naming@0.1.0: {} + + yaml@2.9.0: {} + + yocto-queue@0.1.0: {} + + yoctocolors@2.1.2: {} + + zod-to-json-schema@3.25.0(zod@4.4.3): + dependencies: + zod: 4.4.3 + + zod-to-json-schema@3.25.2(zod@4.4.3): + dependencies: + zod: 4.4.3 + + zod@4.4.3: {} diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml new file mode 100644 index 0000000..664ca3c --- /dev/null +++ b/pnpm-workspace.yaml @@ -0,0 +1,7 @@ +packages: + - "packages/*" + +allowBuilds: + esbuild: true + +minimumReleaseAge: 10080 diff --git a/prettier.config.mjs b/prettier.config.mjs new file mode 100644 index 0000000..206e41e --- /dev/null +++ b/prettier.config.mjs @@ -0,0 +1,13 @@ +/** + * @type {import('prettier').Config} + */ +const config = { + endOfLine: "lf", + singleQuote: false, + tabWidth: 2, + trailingComma: "es5", + printWidth: 100, + arrowParens: "always", +}; + +export default config; diff --git a/public/context7-icon-green.svg b/public/context7-icon-green.svg new file mode 100644 index 0000000..bc73680 --- /dev/null +++ b/public/context7-icon-green.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/public/context7-icon.svg b/public/context7-icon.svg new file mode 100644 index 0000000..123d62e --- /dev/null +++ b/public/context7-icon.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/public/context7-logo.svg b/public/context7-logo.svg new file mode 100644 index 0000000..75c17ba --- /dev/null +++ b/public/context7-logo.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/public/cover.png b/public/cover.png new file mode 100644 index 0000000..ff70828 Binary files /dev/null and b/public/cover.png differ diff --git a/public/icon.png b/public/icon.png new file mode 100644 index 0000000..43ad820 Binary files /dev/null and b/public/icon.png differ diff --git a/rules/context7-cli.md b/rules/context7-cli.md new file mode 100644 index 0000000..def26cb --- /dev/null +++ b/rules/context7-cli.md @@ -0,0 +1,16 @@ +Use the `ctx7` CLI to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs. + +Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts. + +## Steps + +1. Resolve library: `npx ctx7@latest library ""` — use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs") +2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question) +3. Fetch docs: `npx ctx7@latest docs ""` — run a separate `docs` command per distinct concept if the question spans multiple topics, unless it's about how they interact +4. Answer using the fetched documentation + +You MUST call `library` first to get a valid ID unless the user provides one directly in `/org/project` format. Use the user's full question as the query — specific and detailed queries return better results than vague single words, but keep each query to a single concept unless the question is about how concepts interact; combined multi-topic queries dilute ranking and return shallow results for each topic. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries. + +For version-specific docs, use `/org/project/version` from the `library` output (e.g., `/vercel/next.js/v14.3.0`). + +If a command fails with a quota error, inform the user and suggest `npx ctx7@latest login` or setting `CONTEXT7_API_KEY` env var for higher limits. Do not silently fall back to training data. diff --git a/rules/context7-mcp.md b/rules/context7-mcp.md new file mode 100644 index 0000000..bc6ccb3 --- /dev/null +++ b/rules/context7-mcp.md @@ -0,0 +1,10 @@ +Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs. + +Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts. + +## Steps + +1. Always start with `resolve-library-id` using the library name and the user's question, unless the user provides an exact library ID in `/org/project` format +2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question). Use version-specific IDs when the user mentions a version +3. `query-docs` with the selected library ID and the user's full question (not single words), scoped to a single concept. If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic +4. Answer using the fetched docs diff --git a/server.json b/server.json new file mode 100644 index 0000000..6b471c5 --- /dev/null +++ b/server.json @@ -0,0 +1,67 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.upstash/context7", + "title": "Context7", + "description": "Up-to-date code docs for any prompt", + "repository": { + "url": "https://github.com/upstash/context7", + "source": "github" + }, + "websiteUrl": "https://context7.com", + "icons": [ + { + "src": "https://raw.githubusercontent.com/upstash/context7/master/public/icon.png", + "mimeType": "image/png" + } + ], + "version": "2.0.0", + "packages": [ + { + "registryType": "npm", + "identifier": "@upstash/context7-mcp", + "version": "2.0.2", + "transport": { + "type": "stdio" + }, + "environmentVariables": [ + { + "name": "CONTEXT7_API_KEY", + "description": "API key for authentication", + "isRequired": false, + "isSecret": true + } + ] + }, + { + "registryType": "mcpb", + "identifier": "https://github.com/upstash/context7/releases/download/@upstash/context7-mcp@2.0.2/context7.mcpb", + "version": "2.0.2", + "fileSha256": "aea76f179ceb92d22c289147c9d8343fb558d6dec93b144c9794e99239bb8194", + "transport": { + "type": "stdio" + }, + "environmentVariables": [ + { + "name": "CONTEXT7_API_KEY", + "description": "API key for authentication", + "isRequired": false, + "isSecret": true + } + ] + } + ], + "remotes": [ + { + "type": "streamable-http", + "url": "https://mcp.context7.com/mcp", + "headers": [ + { + "name": "CONTEXT7_API_KEY", + "description": "API key for authentication", + "isRequired": false, + "isSecret": true + } + ] + } + ] +} diff --git a/skills/context7-cli/SKILL.md b/skills/context7-cli/SKILL.md new file mode 100644 index 0000000..531aa8a --- /dev/null +++ b/skills/context7-cli/SKILL.md @@ -0,0 +1,72 @@ +--- +name: context7-cli +description: Use the ctx7 CLI to fetch library documentation, manage AI coding skills, and configure Context7 MCP. Activate when the user mentions "ctx7" or "context7", needs current docs for any library, wants to install/search/generate skills, or needs to set up Context7 for their AI coding agent. +--- + +# ctx7 CLI + +The Context7 CLI does three things: fetches up-to-date library documentation, manages AI coding skills, and sets up Context7 MCP for your editor. + +Make sure the CLI is up to date before running commands: + +```bash +npm install -g ctx7@latest +``` + +Or run directly without installing: + +```bash +npx ctx7@latest +``` + +## What this skill covers + +- **[Documentation](references/docs.md)** — Fetch current docs for any library. Use when writing code, verifying API signatures, or when training data may be outdated. +- **[Skills management](references/skills.md)** — Install, search, suggest, list, remove, and generate AI coding skills. +- **[Setup](references/setup.md)** — Configure Context7 MCP for Claude Code / Cursor / OpenCode. + +## Quick Reference + +```bash +# Documentation +ctx7 library # Step 1: resolve library ID +ctx7 docs # Step 2: fetch docs + +# Skills +ctx7 skills install /owner/repo # Install from a repo (interactive) +ctx7 skills install /owner/repo name # Install a specific skill +ctx7 skills search # Search the registry +ctx7 skills suggest # Auto-suggest based on project deps +ctx7 skills list # List installed skills +ctx7 skills remove # Uninstall a skill +ctx7 skills generate # Generate a custom skill with AI (requires login) + +# Setup +ctx7 setup # Configure Context7 MCP (interactive) +ctx7 login # Log in for higher rate limits + skill generation +ctx7 whoami # Check current login status +``` + +## Authentication + +```bash +ctx7 login # Opens browser for OAuth +ctx7 login --no-browser # Prints URL instead of opening browser +ctx7 logout # Clear stored tokens +ctx7 whoami # Show current login status (name + email) +``` + +Most commands work without login. Exceptions: `skills generate` always requires it; `ctx7 setup` requires it unless `--api-key` or `--oauth` is passed. Login also unlocks higher rate limits on docs commands. + +Set an API key via environment variable to skip interactive login entirely: + +```bash +export CONTEXT7_API_KEY=your_key +``` + +## Common Mistakes + +- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react` +- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID +- Repository format for skills is `/owner/repo` — e.g., `ctx7 skills install /anthropics/skills` +- `skills generate` requires login — run `ctx7 login` first diff --git a/skills/context7-cli/references/docs.md b/skills/context7-cli/references/docs.md new file mode 100644 index 0000000..6c06cb7 --- /dev/null +++ b/skills/context7-cli/references/docs.md @@ -0,0 +1,114 @@ +# Documentation Commands + +Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework. Two-step workflow: resolve the library name to get its ID, then query docs using that ID. + +If the user already provided a library ID in `/org/project` or `/org/project/version` format, pass it directly to `ctx7 docs`. + +## Step 1: Resolve a Library + +Resolves a package/product name to a Context7-compatible library ID and returns matching libraries. + +```bash +ctx7 library react "How to clean up useEffect with async operations" +ctx7 library nextjs "How to set up app router with middleware" +ctx7 library prisma "How to define one-to-many relations with cascade delete" +``` + +Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query. + +### Result fields + +Each result includes: + +- **Library ID** — Context7-compatible identifier (format: `/org/project`) +- **Name** — Library or package name +- **Description** — Short summary +- **Code Snippets** — Number of available code examples +- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown) +- **Benchmark Score** — Quality indicator (100 is the highest score) +- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`. + +### Selection process + +1. Analyze the query to understand what library/package the user is looking for +2. Select the most relevant match based on: + - Name similarity to the query (exact matches prioritized) + - Description relevance to the query's intent + - Documentation coverage (prioritize libraries with higher Code Snippet counts) + - Source reputation (consider libraries with High or Medium reputation more authoritative) + - Benchmark score (higher is better, 100 is the maximum) +3. If multiple good matches exist, acknowledge this but proceed with the most relevant one +4. If no good matches exist, clearly state this and suggest query refinements +5. For ambiguous queries, request clarification before proceeding with a best-guess match + +IMPORTANT: Do not call `ctx7 library` more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have. + +### Version-specific IDs + +If the user mentions a specific version, use a version-specific library ID: + +```bash +# General (latest indexed) +ctx7 docs /vercel/next.js "How to set up app router" + +# Version-specific +ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router" +``` + +The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified. + +```bash +# Output as JSON for scripting +ctx7 library react "How to use hooks for state management" --json | jq '.[0].id' +``` + +## Step 2: Query Documentation + +Retrieves up-to-date documentation and code examples for the resolved library. + +You must call `ctx7 library` first to obtain the exact Context7-compatible library ID required to use this command, UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`. + +```bash +ctx7 docs /facebook/react "How to clean up useEffect with async operations" +ctx7 docs /vercel/next.js "How to add authentication middleware to app router" +ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete" +``` + +IMPORTANT: Do not call `ctx7 docs` more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have. + +### Writing good queries + +The query directly affects the quality of results. Be specific and include relevant details, but keep each query to one topic — if the question spans multiple distinct concepts, run a separate `ctx7 docs` command per concept instead of combining them, unless the question is about how the concepts interact. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query. + +| Quality | Example | +|---------|---------| +| Good | `"How to set up authentication with JWT in Express.js"` | +| Good | `"React useEffect cleanup function with async operations"` | +| Bad (too vague) | `"auth"` | +| Bad (too vague) | `"hooks"` | +| Bad (too broad) | `"routing and auth and caching in Next.js"` | + +Use the user's full question as the query when possible — vague one-word queries return generic results, and multi-topic queries dilute ranking and return shallow results for each topic. + +The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context). + +```bash +# Output as structured JSON +ctx7 docs /facebook/react "How to use hooks for state management" --json + +# Pipe to other tools — output is clean when not in a TTY (no spinners or colors) +ctx7 docs /facebook/react "How to use hooks for state management" | head -50 +ctx7 docs /vercel/next.js "How to add middleware for route protection" | grep -A5 "middleware" +``` + +## Authentication + +Works without authentication. For higher rate limits: + +```bash +# Option A: environment variable +export CONTEXT7_API_KEY=your_key + +# Option B: OAuth login +ctx7 login +``` diff --git a/skills/context7-cli/references/setup.md b/skills/context7-cli/references/setup.md new file mode 100644 index 0000000..d8dc5d8 --- /dev/null +++ b/skills/context7-cli/references/setup.md @@ -0,0 +1,43 @@ +# Setup + +## ctx7 setup + +One-time command to configure Context7 for your AI coding agent. Prompts for mode on first run: +- **MCP server** — registers the Context7 MCP server so the agent can call tools natively +- **CLI + Skills** — installs a `find-docs` skill that guides the agent to use `ctx7` CLI commands (no MCP required) + +```bash +ctx7 setup # Interactive — prompts for mode, then agent/install target +ctx7 setup --mcp # Skip prompt, use MCP server mode +ctx7 setup --cli # Skip prompt, use CLI + Skills mode + +# MCP mode — target a specific agent +ctx7 setup --claude # Claude Code only +ctx7 setup --cursor # Cursor only +ctx7 setup --opencode # OpenCode only + +# CLI + Skills mode — target a specific install location +ctx7 setup --cli --claude # Claude Code (~/.claude/skills) +ctx7 setup --cli --cursor # Cursor (~/.cursor/skills) +ctx7 setup --cli --universal # Universal (~/.agents/skills) +ctx7 setup --cli --antigravity # Antigravity (~/.config/agent/skills) + +ctx7 setup --project # Configure current project instead of globally +ctx7 setup --yes # Skip confirmation prompts +``` + +**Authentication options:** +```bash +ctx7 setup --api-key YOUR_KEY # Use an existing API key (both MCP and CLI + Skills mode) +ctx7 setup --oauth # OAuth endpoint — MCP mode only (IDE handles the auth flow) +``` + +Without `--api-key` or `--oauth`, setup opens a browser for OAuth login. MCP mode additionally generates a new API key after login. `--oauth` is MCP-only. + +**What gets written — MCP mode:** +- MCP server entry in the agent's config file (`.mcp.json` for Claude, `.cursor/mcp.json` for Cursor, `.opencode.json` for OpenCode) +- A Context7 rule file instructing the agent to use Context7 for library docs +- A `context7-mcp` skill in the agent's skills directory + +**What gets written — CLI + Skills mode:** +- A `find-docs` skill in the chosen agent's skills directory, guiding the agent to use `ctx7 library` and `ctx7 docs` commands diff --git a/skills/context7-cli/references/skills.md b/skills/context7-cli/references/skills.md new file mode 100644 index 0000000..0a21ee1 --- /dev/null +++ b/skills/context7-cli/references/skills.md @@ -0,0 +1,118 @@ +# Skills Commands + +Manage AI coding skills from the Context7 registry. Skills are Markdown files that teach AI coding agents best practices, patterns, and workflows for specific libraries or tasks. + +## Install + +Install skills from any GitHub repository. Repository format is always `/owner/repo`. + +```bash +ctx7 skills install /anthropics/skills # Interactive — pick from a list +ctx7 skills install /anthropics/skills pdf # Install a specific skill by name +ctx7 skills install /anthropics/skills --all # Install everything without prompting +``` + +Target a specific IDE with a flag: +```bash +ctx7 skills install /anthropics/skills pdf --claude # Claude Code only +ctx7 skills install /anthropics/skills pdf --cursor # Cursor only +ctx7 skills install /anthropics/skills pdf --universal # Universal (.agents/skills/) +ctx7 skills install /anthropics/skills --all --global # All skills, global install +``` + +Alias: `ctx7 si /anthropics/skills pdf` + +## Search + +Find skills across the entire registry by keyword. Shows an interactive list with install counts and trust scores. Select to install. + +```bash +ctx7 skills search pdf +ctx7 skills search typescript testing +ctx7 skills search react nextjs +``` + +Alias: `ctx7 ss pdf` + +## Suggest + +Auto-detects your project dependencies and recommends relevant skills from the registry. + +```bash +ctx7 skills suggest # Scan current project, install to project +ctx7 skills suggest --global # Install suggestions globally +ctx7 skills suggest --claude # Target Claude Code only +``` + +Reads `package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`. Falls back to suggesting `ctx7 skills search` if no dependencies are detected. + +Alias: `ctx7 ssg` + +## Generate (AI-powered) + +Generate a custom skill tailored to your stack using AI. **Requires login.** + +```bash +ctx7 skills generate +ctx7 skills generate --claude # Install directly to Claude Code +ctx7 skills generate --global # Install to global skills +``` + +Interactive flow: +1. Describe the expertise you want (e.g., "OAuth authentication with NextAuth.js") +2. Select relevant libraries from search results +3. Answer 3 clarifying questions to focus the skill +4. Review the generated skill, request changes if needed +5. Choose where to install it + +**Limits:** Free accounts get 6 generations/week, Pro accounts get 10. + +Aliases: `ctx7 skills gen`, `ctx7 skills g` + +## List + +Show all installed skills for the current project or globally. + +```bash +ctx7 skills list # Current project (all detected IDEs) +ctx7 skills list --claude # Claude Code only +ctx7 skills list --global # Global skills +ctx7 skills list --global --claude # Global Claude Code skills +``` + +## Remove + +Uninstall a skill by name. + +```bash +ctx7 skills remove pdf +ctx7 skills remove pdf --claude # From Claude Code only +ctx7 skills remove pdf --global # From global skills +``` + +Aliases: `ctx7 skills rm`, `ctx7 skills delete` + +## Info + +Browse all skills in a repository without installing — useful for previewing what's available. + +```bash +ctx7 skills info /anthropics/skills +``` + +Output shows each skill name, description, and URL, plus quick install commands. + +## IDE Flags + +All skills commands accept these flags to target a specific AI coding assistant: + +| Flag | Directory | Used by | +|------|-----------|---------| +| `--universal` | `.agents/skills/` | Amp, Codex, Gemini CLI, OpenCode, GitHub Copilot | +| `--claude` | `.claude/skills/` | Claude Code | +| `--cursor` | `.cursor/skills/` | Cursor | +| `--antigravity` | `.agent/skills/` | Antigravity | + +Without a flag, the CLI prompts you to select one or more targets interactively. + +Add `--global` to any flag to install in your home directory instead of the current project. diff --git a/skills/context7-mcp/SKILL.md b/skills/context7-mcp/SKILL.md new file mode 100644 index 0000000..245b080 --- /dev/null +++ b/skills/context7-mcp/SKILL.md @@ -0,0 +1,56 @@ +--- +name: context7-mcp +description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc. +--- + +When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data. + +## When to Use This Skill + +Activate this skill when the user: + +- Asks setup or configuration questions ("How do I configure Next.js middleware?") +- Requests code involving libraries ("Write a Prisma query for...") +- Needs API references ("What are the Supabase auth methods?") +- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## How to Fetch Documentation + +### Step 1: Resolve the Library ID + +Call `resolve-library-id` with: + +- `libraryName`: The library name extracted from the user's question +- `query`: The user's full question (improves relevance ranking) + +### Step 2: Select the Best Match + +From the resolution results, choose based on: + +- Exact or closest name match to what the user asked for +- Higher benchmark scores indicate better documentation quality +- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs + +### Step 3: Fetch the Documentation + +Call `query-docs` with: + +- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`) +- `query`: The user's specific question, scoped to a single concept + +If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic. + +### Step 4: Use the Documentation + +Incorporate the fetched documentation into your response: + +- Answer the user's question using current, accurate information +- Include relevant code examples from the docs +- Cite the library version when relevant + +## Guidelines + +- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact +- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step +- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks diff --git a/skills/find-docs/SKILL.md b/skills/find-docs/SKILL.md new file mode 100644 index 0000000..da5f683 --- /dev/null +++ b/skills/find-docs/SKILL.md @@ -0,0 +1,159 @@ +--- +name: find-docs +description: >- + Retrieves up-to-date documentation, API references, and code examples for any + developer technology. Use this skill whenever the user asks about a specific + library, framework, SDK, CLI tool, or cloud service — even for well-known ones + like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. Your + training data may not reflect recent API changes or version updates. + + Always use for: API syntax questions, configuration options, version migration + issues, "how do I" questions mentioning a library name, debugging that involves + library-specific behavior, setup instructions, and CLI tool usage. + + Use even when you think you know the answer — do not rely on training data + for API details, signatures, or configuration options as they are frequently + outdated. Always verify against current docs. Prefer this over web search for + library documentation and API details. +--- + +# Documentation Lookup + +Retrieve current documentation and code examples for any library using the Context7 CLI. + +Run commands with `npx ctx7@latest` so setup always uses the latest CLI without a global install: + +```bash +npx ctx7@latest library "" +npx ctx7@latest docs "" +``` + +Optionally install globally if you prefer a bare `ctx7` command: + +```bash +npm install -g ctx7@latest +``` + +## Workflow + +Two-step process: resolve the library name to an ID, then query docs with that ID. + +```bash +# Step 1: Resolve library ID +npx ctx7@latest library "" + +# Step 2: Query documentation +npx ctx7@latest docs "" +``` + +You MUST call `library` first to obtain a valid library ID UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`. + +IMPORTANT: Do not run these commands more than 3 times per question. If you cannot find what you need after 3 attempts, use the best result you have. + +## Step 1: Resolve a Library + +Resolves a package/product name to a Context7-compatible library ID and returns matching libraries. + +```bash +npx ctx7@latest library React "How to clean up useEffect with async operations" +npx ctx7@latest library "Next.js" "How to set up app router with middleware" +npx ctx7@latest library Prisma "How to define one-to-many relations with cascade delete" +``` + +Use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs"). If results look wrong, try alternate spellings such as `next.js` before changing the query. + +Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query. + +### Result fields + +Each result includes: + +- **Library ID** — Context7-compatible identifier (format: `/org/project`) +- **Name** — Library or package name +- **Description** — Short summary +- **Code Snippets** — Number of available code examples +- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown) +- **Benchmark Score** — Quality indicator (100 is the highest score) +- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`. + +### Selection process + +1. Analyze the query to understand what library/package the user is looking for +2. Select the most relevant match based on: + - Name similarity to the query (exact matches prioritized) + - Description relevance to the query's intent + - Documentation coverage (prioritize libraries with higher Code Snippet counts) + - Source reputation (consider libraries with High or Medium reputation more authoritative) + - Benchmark score (higher is better, 100 is the maximum) +3. If multiple good matches exist, acknowledge this but proceed with the most relevant one +4. If no good matches exist, clearly state this and suggest query refinements +5. For ambiguous queries, request clarification before proceeding with a best-guess match + +### Version-specific IDs + +If the user mentions a specific version, use a version-specific library ID: + +```bash +# General (latest indexed) +npx ctx7@latest docs /vercel/next.js "How to set up app router" + +# Version-specific +npx ctx7@latest docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router" +``` + +The available versions are listed in the `library` command output. Use the closest match to what the user specified. + +## Step 2: Query Documentation + +Retrieves up-to-date documentation and code examples for the resolved library. + +```bash +npx ctx7@latest docs /facebook/react "How to clean up useEffect with async operations" +npx ctx7@latest docs /vercel/next.js "How to add authentication middleware to app router" +npx ctx7@latest docs /prisma/prisma "How to define one-to-many relations with cascade delete" +``` + +### Writing good queries + +The query directly affects the quality of results. Be specific and include relevant details, but keep each query to one topic — if the question spans multiple distinct concepts, run a separate `docs` command per concept instead of combining them, unless the question is about how the concepts interact. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query. + +| Quality | Example | +|---------|---------| +| Good | `"How to set up authentication with JWT in Express.js"` | +| Good | `"React useEffect cleanup function with async operations"` | +| Bad (too vague) | `"auth"` | +| Bad (too vague) | `"hooks"` | +| Bad (too broad) | `"routing and auth and caching in Next.js"` | + +Use the user's full question as the query when possible — vague one-word queries return generic results, and multi-topic queries dilute ranking and return shallow results for each topic. + +The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context). + +## Authentication + +Works without authentication. For higher rate limits: + +```bash +# Option A: environment variable +export CONTEXT7_API_KEY=your_key + +# Option B: OAuth login +npx ctx7@latest login +``` + +## Error Handling + +If a command fails with a quota error ("Monthly quota reached" or "quota exceeded"): +1. Inform the user their Context7 quota is exhausted +2. Suggest they authenticate for higher limits: `npx ctx7@latest login` +3. If they cannot or choose not to authenticate, answer from training knowledge and clearly note it may be outdated + +Do not silently fall back to training data — always tell the user why Context7 was not used. + +## Common Mistakes + +- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react` +- Always run `npx ctx7@latest library` first — `npx ctx7@latest docs react "hooks"` will fail without a valid ID +- Use descriptive queries, not single words — `"React useEffect cleanup function"` not `"hooks"` +- One topic per query — split `"routing and auth and caching"` into a separate `docs` command per concept, unless the question is about how they interact +- Do not include sensitive information (API keys, passwords, credentials) in queries diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..5647feb --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,13 @@ +{ + "compilerOptions": { + "target": "ES2022", + "lib": ["ES2022"], + "moduleResolution": "Node16", + "module": "Node16", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true + }, + "exclude": ["node_modules", "dist", "build"] +}