pi package
Overview
packages/pi publishes @upstash/context7-pi, the Context7 extension for the pi coding agent. The package entrypoints are declared in packages/…/package.json under the pi manifest: ./extensions for executable extensions, ./skills for bundled agent guidance, and ./prompts for slash-command assets. The published package includes extensions, lib, skills, prompts, LICENSE, and README.md; changes outside that files list will not ship to pi users unless packages/…/package.json is updated.
The runtime extension is packages/…/context7.ts. Its default export receives pi's ExtensionAPI and registers exactly two tools: resolveLibraryIdTool from packages/…/resolve-library-id.ts and queryDocsTool from packages/…/query-docs.ts. There is no package-local state beyond process environment reads for authentication; both tools call the public Context7 HTTP API at https://context7.com/api through helpers in packages/…/api.ts.
resolve-library-id is defined in packages/…/resolve-library-id.ts. Its TypeBox parameter schema requires query and libraryName, with descriptions sourced from packages/…/prompts.ts. Execution calls searchLibraries(query, libraryName) in packages/…/api.ts, which performs GET /v2/libs/search with those values as URL search parameters and adds Authorization: Bearer $CONTEXT7_API_KEY when the environment variable is present. Successful responses are typed as SearchResponse from packages/…/types.ts; empty results return the API error if present or No libraries found matching the provided name.; non-empty results are rendered as `Available Libraries:
${formatSearchResults(...)}`.
query-docs is defined in packages/…/query-docs.ts. Its TypeBox parameter schema requires libraryId and query, again using text from packages/…/prompts.ts. Execution calls fetchLibraryContext(query, libraryId) in packages/…/api.ts, which performs GET /v2/context, returns response text on success, and returns human-readable error text instead of throwing on non-OK responses. Empty successful bodies are converted to guidance telling the agent to obtain a valid Context7-compatible library ID with resolve-library-id.
All tool results are normalized by packages/…/result.ts, which wraps text as pi AgentToolResult<undefined> with one { type: "text", text } content item and details: undefined. Search output formatting lives in packages/…/format.ts: each result includes title, Context7 library ID, description, source reputation derived from trustScore, and conditionally code snippet count, benchmark score, versions, and source. formatSearchResults also prepends a teamspace library-filter note when SearchResponse.searchFilterApplied is true. The wire types in packages/…/types.ts mirror the Context7 MCP search response: SearchResult, SearchResponse, and DocumentState.
Agent-facing guidance is split between code constants and pi assets. packages/…/prompts.ts contains the tool labels, descriptions, and parameter descriptions shown to the model by the registered tools; the text instructs callers to resolve a library ID before querying docs unless the user already supplied /org/project or /org/project/version, limits repeated calls, and warns not to send secrets in the query. packages/…/SKILL.md is the bundled pi skill that tells the agent when to use Context7, describes the resolve-then-query workflow, and documents the CONTEXT7_API_KEY environment variable. packages/…/c7-docs.md is the /c7-docs <library> <question> slash command: it maps $1 to libraryName, ${@:2} to the documentation query, skips resolution for already-valid Context7 IDs, then asks the agent to summarize with code examples and cite the library ID.
packages/…/extension.test.ts verifies the extension contract from pi's perspective. It constructs a fake ExtensionAPI, collects registered tools, asserts that query-docs and resolve-library-id are registered with the expected parameter keys and Context7 descriptions, and includes a live Context7 API smoke test for resolving React. Test configuration in packages/…/vitest.config.ts runs Node-environment tests matching __tests__/…/*.test.ts and loads the repository-level .env so CONTEXT7_API_KEY can be supplied locally. TypeScript includes extensions/**/*, lib/**/*, __tests__/**/*, vitest.config.ts, and eslint.config.js via packages/…/tsconfig.json, which extends the repo bundler config. Linting rules are package-local in packages/…/eslint.config.js, using typescript-eslint with parserOptions.project: "./tsconfig.json" and Prettier enforcement.
Coupling
- If any Context7 API response shape changes, update packages/…/types.ts, packages/…/api.ts, and packages/…/format.ts together.
searchLibrariescasts JSON directly toSearchResponse, andformatSearchResultsreads optional fields without runtime validation, so API drift can silently change or omit text shown to agents. - If tool names, parameter names, labels, or descriptions change in packages/…/resolve-library-id.ts, packages/…/query-docs.ts, or packages/…/prompts.ts, also update packages/…/SKILL.md, packages/…/c7-docs.md, packages/…/README.md, and packages/…/extension.test.ts. The skill and slash command refer to
resolve-library-id,query-docs,libraryName,libraryId, andqueryliterally, and the tests assert those names. - If output formatting changes in packages/…/format.ts or error text changes in packages/…/api.ts, verify parity with the upstream MCP implementation referenced in the file comments. The pi package intentionally copies MCP wire types, formatter behavior, tool descriptions, and error messages so pi and MCP clients produce the same LLM-visible contract.
- If new extension, skill, prompt, or runtime directories are added under
packages/pi, make sure packages/…/package.json includes them in both thepimanifest when pi must discover them and thefilesarray when npm must publish them. Otherwise local tests may pass while installed pi packages omit the asset. - If authentication behavior changes in packages/…/api.ts, update packages/…/README.md and packages/…/SKILL.md; both currently tell users that
CONTEXT7_API_KEYcontrols authenticated Context7 requests.
Risks
- packages/…/extension.test.ts contains a live network test against Context7 with a 15-second timeout. If Context7 is unavailable, rate-limited, or the test environment lacks expected network access,
pnpm --filter @upstash/context7-pi testcan fail even when the extension registration code is correct. - packages/…/api.ts returns error messages as normal tool text rather than throwing or tagging errors in
details. If callers start relying on structured failure metadata, failures fromsearchLibrariesandfetchLibraryContextwill look like successful text results because packages/…/result.ts always emitsdetails: undefined. - packages/…/format.ts, packages/…/types.ts, and packages/…/prompts.ts are intentionally copied from the MCP package according to their comments. If a change is made only in pi, agents using pi and MCP can receive different tool instructions or search-result formatting for the same Context7 request.