Skip to main content
Glama
ayhammouda

python-docs-mcp-server

by ayhammouda
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

python-docs-mcp-server

For AI coding agents writing Python, python-docs-mcp-server is the canonical Python stdlib oracle: exact symbols, exact sections, exact versions — offline, always free, always MIT, token-frugal.

CI Security Audit CodeQL OpenSSF Scorecard python-docs-mcp-server MCP server MCP Registry License: MIT Python 3.12+ No API Keys Official Python Docs

Built for the moment your agent needs asyncio.TaskGroup signatures, pathlib.Path semantics, or what changed in 3.12 — not a web fetch, not a hosted API, not a vector store hallucinating section anchors. Just an indexed slice of docs.python.org, returned by symbol or by query, scoped to the version you actually ship on.

Why this exists

There is a difference between long context and usable context. Research like the Lost in the Middle study (Liu et al., 2023) found that models struggle to use relevant information buried in the middle of a long input. Pasting an entire documentation page into the model invites that failure. Returning the exact symbol, section, and version keeps the answer in a short, high-signal context instead.

Generic docs retrieval is a rough fit for Python stdlib questions:

  • asyncio.TaskGroup should resolve to the actual symbol, not a fuzzy page hit

  • Python version matters (3.12 and 3.13 do not always say the same thing)

  • fetching a whole page burns tokens when one section answers the question

  • the official docs are canonical, but they do not ship as an MCP server

This server indexes the official docs locally and exposes a small set of MCP tools for lookup and section retrieval.

Related MCP server: Context7 MCP

Why use it

  • no API keys to manage

  • queries run against a local index, not a hosted docs API

  • results come from the official Python docs

  • the server is read-only at runtime

  • fewer dependencies to review in strict environments

What you get

  • symbol lookup through Python objects.inv

  • page and section retrieval with truncation and pagination

  • a local SQLite + FTS5 index; no runtime web scraping

  • results for each Python version you index

  • seven read-only MCP tools

Quick example

Prompt

What does asyncio.TaskGroup do in Python 3.13?

Typical flow

  1. search_docs("asyncio.TaskGroup", kind="symbol", version="3.13")

  2. Call get_docs(...) using the slug and anchor returned by the best hit

Result

The model gets the matching symbol and the relevant docs section, not a full-page dump.

30-second demo

Ask your MCP client:

In Python 3.13, how should I use asyncio.TaskGroup and what changed from older asyncio patterns?

If setup is working, the client should use search_docs for the exact symbol, then get_docs for the matching section. Instead of generic web results or an entire docs page, it gets official stdlib text for the requested Python version, trimmed to the section that matters.

Install

Run directly with uvx:

uvx python-docs-mcp-server --version

Or install it once with pipx:

pipx install python-docs-mcp-server

If uv is installed but the uv command is not on your PATH, reopen your shell or use python -m uv ... as a fallback for local contributor commands.

Search result behavior

For kind="auto" with an explicit version, a nonempty search with spare result slots may append one exact inventory target when the prompt contains one known qualified identifier in that version. Original hits, snippets, scores, order and notes are preserved. Full results, ambiguous identifiers, other kinds and versionless queries are unchanged; the existing empty-result fallback is unchanged. Canonical locations are deduplicated, including inventory aliases.

The append is admitted only when the complete proposed response serialized by Pydantic's compact model_dump_json() is at most 8000 UTF-8 bytes. This is not a global search cap: oversized original responses remain unchanged. It is separate from get_docs(max_chars=8000), which limits content characters.

First run

Build the local documentation index:

uvx python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14

If you installed the package persistently, you can drop the uvx prefix:

python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14

The first build downloads Python's objects.inv files, clones CPython docs sources, runs sphinx-build -b json, and writes an SQLite index to your local cache. It can take several minutes.

Python 3.15 documentation (opt-in)

The source-pinned documentation targets include Python 3.10–3.15. To index 3.15 alongside 3.14, explicitly run:

uvx python-docs-mcp-server build-index --versions 3.14,3.15

A build replaces the local index with the requested versions; include every version you want to keep. The first-run examples above intentionally remain unchanged. The builder still marks the highest requested version as the index default; adding this target does not select 3.15 in an existing index. get_docs without a version uses the configured/detected default, while versionless search spans indexed versions. Pass version="3.15" for isolated 3.15 answers. list_versions reports the actual index, not all build targets; an unindexed explicit version raises an error, never an older-docs fallback.

This is documentation coverage, not a claim that the server runs on Python 3.15 or that a named MCP client was tested with it. Queries remain offline and read-only after a successful build. Until it is indexed, consult the official 3.15 docs directly.

The 3.15 target is CPython tag v3.15.0, commit d220409a13b77de7a6c30abe16ea90db01528edc, with Sphinx 8.2.3. See integration checks for explicit-version and comparison examples.

Configure your MCP client

Claude Code

This repository includes a project-scoped .mcp.json for clients that support checked-in MCP server configuration. It points at the published package:

{
  "mcpServers": {
    "python-docs": {
      "type": "stdio",
      "command": "uvx",
      "args": ["python-docs-mcp-server"]
    }
  }
}

Build the local documentation index with the first-run command above before expecting docs queries to return corpus-backed results.

Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "python-docs": {
      "command": "uvx",
      "args": ["python-docs-mcp-server"]
    }
  }
}

Restart Claude Desktop after editing the config file.

Cursor

Add this to your Cursor MCP settings (.cursor/mcp.json in your project or global settings):

{
  "mcpServers": {
    "python-docs": {
      "command": "uvx",
      "args": ["python-docs-mcp-server"]
    }
  }
}

Codex

Add this to .codex/config.toml:

[mcp_servers.python-docs]
command = "uvx"
args = ["python-docs-mcp-server"]

Quality checks

  • CI runs ruff, pyright, and pytest on macOS and Linux for Python 3.12 and 3.13

  • subprocess-based stdio and smoke tests cover the MCP protocol pipe

  • packaging tests check the wheel contents and CLI entry points

  • retrieval regression tests cover exact symbol hits, version behavior, missing symbols, truncation, and local-version defaults

  • manual MCP QA lives in .github/INTEGRATION-TEST.md, with MCP Inspector for local checks and Claude/Cursor for real-client checks

Contributor commands and validation steps live in CONTRIBUTING.md.

Tools

The server currently exposes seven MCP tools:

Tool

Description

search_docs

Search Python stdlib docs by query. Supports symbol lookup (asyncio.TaskGroup), module search (json), and free-text search. Returns ranked hits with BM25 scoring and snippet excerpts.

get_docs

Retrieve a specific documentation page or section by slug and optional anchor. Returns markdown content with budget-enforced truncation and pagination. Retrieved results are cached on disk by Python docs version and request identity.

lookup_package_docs

Look up official PyPI package metadata and return package-declared documentation/homepage/source URLs. This is a controlled PyPI metadata lookup, not generic web search.

list_versions

List all indexed Python versions with metadata.

detect_python_version

Detect the user's local Python version and report whether that version has been indexed.

compare_versions

Diff a Python stdlib symbol between two indexed versions. Returns `change=added

whatsnew_for_version

Browse nonempty sections of the already-indexed official What's New page for one Python version. Optional kind filters by conservative heading-hierarchy category. start_index and max_sections paginate the filtered results; the structured response is capped at 20,000 characters, and truncated excerpts include a stable anchor and get_docs follow-up hint. Canonical titles and anchors are unchanged; if one section cannot fit its metadata plus nonempty indexed text and any required continuation hint, an explicit bounded error is returned. Page size may be reduced to reserve usable excerpts. The cap counts Unicode characters in the model JSON, excluding the MCP envelope. Querying is offline.

For search_docs with kind="auto" and an explicit indexed version, the original lookup and full-text search run first. If both return no hits, the server looks for dotted Python identifiers in the prompt. Exactly one distinct identifier registered in that version enables a symbol-lookup fallback; repeated mentions count once and unknown identifiers do not count. Multiple known identifiers leave the result empty. A result note identifies fallback matches, which are symbol documentation, not an answer to the complete prompt. Explicit kinds, searches without a version, nonempty results, and result budgets are unchanged.

Why not Context7 or generic docs retrieval?

Use this server when you want precise local Python docs retrieval rather than broad web search:

  • official Python docs, not scraped mirrors or summaries

  • exact symbol resolution from objects.inv

  • version-aware results for Python 3.10 through 3.14

  • section retrieval instead of full-page dumps

  • PyPI-declared docs, homepage, and source links through lookup_package_docs

  • local read-only runtime with no API keys

Use Context7 or a generic docs fetcher for third-party libraries, arbitrary web pages, or framework research. This server is not a universal docs search engine; it is a focused stdlib retrieval tool for AI coding agents.

Retrieved docs cache

get_docs responses are cached across MCP client/server restarts in the platform cache directory:

<platform cache dir>/mcp-python-docs/retrieved-docs-cache.sqlite3

The cache stores completed get_docs results for the resolved Python docs version plus request identity (slug, optional anchor, max_chars, and start_index). Cache misses use the normal local index retrieval path and then write the result.

Cache entries are also scoped to a fingerprint of the local index.db file (path, size, and modification timestamp). If you rebuild or replace the local docs index, older entries are ignored automatically. Deleting retrieved-docs-cache.sqlite3 is safe; it removes cached retrieval results, not the docs index.

PyPI package docs lookup

lookup_package_docs queries the official PyPI JSON API documented at https://docs.pypi.org/api/json/ (GET /pypi/<project>/json) and returns only sources declared in that package's PyPI metadata: the PyPI project URL, docs_url, home_page, and allowlisted project_urls labels such as Documentation, Homepage, Source, and Repository.

The tool makes the trust boundary explicit with trust_boundary="pypi-declared-metadata". It does not crawl pages, perform web search, or silently fall back to unofficial community mirrors.

Diagnostics

Check the local environment:

uvx python-docs-mcp-server doctor

This checks the runtime Python version, SQLite FTS5, cache/index paths, disk space, and the venv/ensurepip support needed by build-index.

Validate an existing index:

uvx python-docs-mcp-server validate-corpus

Troubleshooting

FTS5 unavailable

If your Python build does not include SQLite FTS5:

Linux x86-64

Linux x86-64 users can install the optional bundled SQLite package:

pip install 'python-docs-mcp-server[pysqlite3]'

macOS / Windows / Linux ARM

Install Python from python.org or use:

uv python install

Missing pythonX.Y-venv on Debian/Ubuntu

If doctor says build venv support is unavailable, install the venv package for the same Python minor version that runs the server:

sudo apt install python3.12-venv

Adjust 3.12 to match the version shown by doctor. Without this package, build-index cannot create the disposable Sphinx environment it uses to build JSON documentation content.

Migrating from the pre-rename CLI

Earlier development snapshots of this project used the PyPI name mcp-server-python-docs. The published PyPI project is python-docs-mcp-server. If your MCP client config still references the old name via uvx, you will see a Package not found error, because uvx resolves projects by PyPI name.

Change your config args from:

"args": ["mcp-server-python-docs"]

to:

"args": ["python-docs-mcp-server"]

The wheel still installs a legacy mcp-server-python-docs console script for users who already have the package installed and invoke the binary by name on $PATH. That script is an alias and will be removed in a future release.

uvx cache stale

If uvx python-docs-mcp-server runs an old version:

uvx --reinstall python-docs-mcp-server

Or clear the uv cache:

uv cache clean python-docs-mcp-server

Claude Desktop on Windows (MSIX)

The MSIX-packaged version of Claude Desktop on Windows may have restricted PATH access. If uvx is not found, specify the full path in your config:

{
  "mcpServers": {
    "python-docs": {
      "command": "C:\\Users\\YOU\\.local\\bin\\uvx.exe",
      "args": ["python-docs-mcp-server"]
    }
  }
}

Replace YOU with your Windows username. Find the exact path with where uvx.

Restart after rebuild

After running build-index, restart your MCP client so it picks up the new database file. The server opens the index read-only on startup and does not reload it while running.

On Windows, close the MCP client before rebuilding if the index file is locked.

Contributor workflow

For contributor setup and verification:

Support

Tested on macOS and Linux. Windows should work, but it is not verified on every release.

The server requires Python 3.12+ to run. Source-pinned documentation targets cover Python 3.10 through 3.15; Python 3.15 is opt-in. The versions available for queries depend on the documentation versions selected when building the index.

License

MIT

Available Tools

7 tools
compare_versionsA
Read-onlyIdempotent

Diff a Python stdlib symbol between two indexed versions. Returns change=added|removed|changed|unchanged with optional new_in, changed_in, deprecated_in, signature_delta (advisory), see_also_added/removed, section_diff, and note fields. Both versions must be indexed; otherwise an actionable error names the available versions.

NameRequiredDescriptionDefault
v1YesPython version string, e.g. '3.11'
v2YesPython version string, e.g. '3.11'
symbolYesQualified Python symbol name, e.g. 'asyncio.TaskGroup'

Output Schema

NameRequiredDescription
v1YesSource Python version
v2YesTarget Python version
noteNoOptional advisory note about result completeness, e.g. when docs pages could not be fetched for one or both versions and the diff is therefore based on symbol presence alone.
changeYesDiff discriminator: 'added' (symbol new in v2), 'removed' (symbol absent in v2), 'changed' (symbol present in both with a detected delta), or 'unchanged' (symbol present in both, no delta)
new_inNoVersion string extracted from the v2 section text; populated when change == 'added', and may also be set when change == 'changed' if the v2 section carries a versionadded marker for a sub-feature
symbolYesQualified symbol name being compared
changed_inNoVersion extracted from the v2 section; populated when change == 'changed'
removed_inNoVersion where the symbol is first absent; populated when change == 'removed' (equals v2)
section_diffNoShort unified-diff snippet (difflib.unified_diff), truncated to honor the token budget; populated only when change == 'changed' and the diff is non-trivially short
deprecated_inNoVersion extracted from a deprecation marker in the v2 section
see_also_addedNoSee-also link labels present in v2 but not v1
signature_deltaNoBest-effort heuristic: first non-empty diff line between v1 and v2 section text. MAY be a docstring change or prose change rather than a true signature change — treat as advisory, not authoritative.
see_also_removedNoSee-also link labels present in v1 but not v2

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond annotations by detailing the return structure (change type, optional fields) and error behavior for unindexed versions. This adds significant transparency for an AI agent, and there is no contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences. The first sentence immediately states the core purpose and output, and the second adds essential error handling info. Every sentence adds value with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema and clear annotations, the description covers key aspects: core function, return fields, and error handling. It is complete for an AI agent to understand when and how to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides clear descriptions for all three parameters (100% coverage). The description adds minimal extra context beyond stating the condition that versions must be indexed, which is a minor enhancement. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool diffs a Python stdlib symbol between two indexed versions, using a specific verb and resource. It distinguishes itself from siblings (e.g., list_versions, detect_python_version) by focusing on comparing a single symbol across versions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a condition that both versions must be indexed and mentions actionable error messages, which implies proper usage context. However, it does not explicitly state when to use this tool over alternatives or provide negative examples.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

detect_python_versionA
Read-onlyIdempotent

Detect the Python version in the user's environment. Returns the detected version, how it was found, and whether it matches an indexed documentation set.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
sourceYesHow the version was detected: '.python-version file', 'python3 in PATH', or 'server runtime'
is_defaultYesWhether this detected version is being used as the default for get_docs
detected_versionYesPython major.minor detected from the user's environment (e.g. '3.13')
matched_index_versionNoThe detected version if it matches an indexed doc set, otherwise null

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, and non-destructive. The description adds value by detailing what the tool returns (detected version, method of detection, and match status), providing context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the main purpose. Every sentence adds information without redundancy. Extremely efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description correctly avoids repeating return details. It covers the tool's core function and expected outputs, providing sufficient completeness for a simple detection tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist (0 params, 100% schema coverage baseline). The description does not need to add parameter details, so a baseline of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it detects the Python version in the user's environment, which is a specific verb-resource pair. It distinguishes itself from sibling tools like list_versions or compare_versions by focusing on the local environment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use versus alternatives. While the purpose is clear, an agent could benefit from knowing this is for detecting the current environment's version, not for comparing or listing all versions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_docsA
Read-onlyIdempotent

Retrieve a documentation page or specific section. Provide anchor for section-only retrieval (much cheaper). Pagination via start_index.

NameRequiredDescriptionDefault
slugYesPage slug (e.g. 'library/asyncio-task.html')
anchorNoSection anchor for section-only retrieval
versionNoPython version (e.g. '3.13'). Defaults to latest.
max_charsNoMaximum characters to return
start_indexNoStart position for pagination

Output Schema

NameRequiredDescription
slugYesPage slug
titleYesPage or section title
anchorNoSection anchor if section-level
contentYesDocumentation content in markdown
versionYesPython version
truncatedNoWhether content was truncated
char_countYesTotal character count of full content
next_start_indexNoNext start_index for pagination, if truncated

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly, non-destructive, idempotent. The description adds behavioral context: anchor retrieval is 'much cheaper', and pagination is available via start_index. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main purpose, followed by two essential usage tips. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and 100% schema coverage, the description doesn't need to cover return values. It adequately explains the key parameters and usage nuances (anchor, pagination). Slight omission: no mention of version default behavior, but that is in schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description's value-add is limited. However, it explains the purpose of 'anchor' (section-only retrieval) and 'start_index' (pagination), which goes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Retrieve') and the resource ('documentation page or specific section'), distinguishing it from siblings like search_docs and compare_versions. It also mentions key features: anchor for section-only retrieval and pagination.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides guidance on using anchor for cheaper section-only retrieval and mentions pagination via start_index. However, it does not explicitly state when not to use this tool or compare it with alternatives like search_docs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_versionsA
Read-onlyIdempotent

List Python documentation versions available in this index.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
versionsYesAvailable documentation versions

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds minimal behavioral context by specifying the scope 'in this index', but does not disclose additional traits like return format or pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the action and resource. Every word is necessary and there is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, annotations cover safety, and an output schema exists, the description is complete enough. It states the core purpose without missing crucial information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is 100%. The description adds no parameter-specific meaning beyond what the schema provides, but baseline is 4 for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'List' and identifies the resource 'Python documentation versions' with scope 'in this index'. It clearly distinguishes this tool from siblings like compare_versions or search_docs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when an agent needs to know available versions in this index, but does not explicitly state when to use or not use it versus alternatives. It provides clear context but no exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lookup_package_docsA
Read-onlyIdempotent

Look up package-declared docs/homepage/source URLs via official PyPI metadata.

This is not generic web search: it only queries PyPI's JSON API and returns official PyPI metadata plus package-declared project URLs.

NameRequiredDescriptionDefault
packageYesPyPI package/project name

Output Schema

NameRequiredDescription
noteNoControlled-scope note, for example skipped labels or not-found details
packageYesCanonical package name returned by PyPI when available
sourcesNoPackage-declared PyPI, documentation, homepage, and source URLs
summaryNoPackage summary from PyPI metadata
versionYesLatest version reported by PyPI metadata
trust_boundaryNoIndicates results are limited to PyPI/project-declared metadata
metadata_sourceYesOfficial PyPI JSON API URL used for lookup

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that it only queries PyPI's JSON API and returns official metadata and project URLs, providing behavioral context beyond annotations. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs, front-loaded with purpose, followed by clarifying scope. Every sentence adds value with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one simple parameter, high schema coverage, output schema exists, and annotations covering safety, the description provides all necessary context: what it does, its data source, and its limitations. Complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already describes the 'package' parameter as 'PyPI package/project name'. The description does not add new meaning beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it looks up package-declared docs/homepage/source URLs via official PyPI metadata, using specific verb 'look up' and resource 'package-declared URLs'. It distinguishes from generic web search and from siblings like search_docs by emphasizing it only queries PyPI's JSON API.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states it is not generic web search and only queries PyPI's JSON API, providing clear context on when not to use. While it does not explicitly name siblings as alternatives, the contrast with general search is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_docsA
Read-onlyIdempotent

Search Python documentation. Use kind='symbol' for API lookups (asyncio.TaskGroup), kind='example' for code samples, kind='auto' otherwise. When version is omitted, searches across all versions. Pass the version from each hit's version field to get_docs for consistent results.

NameRequiredDescriptionDefault
kindNoSearch type. Use 'symbol' for API lookups, 'example' for code samples, 'auto' otherwise.auto
queryYesSearch query - Python symbol (asyncio.TaskGroup) or concept (parse json)
versionNoPython version (e.g. '3.13'). Defaults to latest.
max_resultsNoMaximum number of results to return.

Output Schema

NameRequiredDescription
hitsNoSearch result hits
noteNoInformational note (e.g., limited search mode)

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate read-only and idempotent. Description adds that omitting version searches all versions and that results have a version field for use with get_docs. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, 57 words, front-loaded with purpose, then specific usage. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given output schema exists and annotations are present, the description adequately covers usage. Mentions sibling tool get_docs for consistency, but could clarify relationship with other siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds usage context for kind and clarifies that omitting version means all versions (not just 'latest' as schema implies). Provides extra value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search Python documentation' with specific verb and resource. It provides details on kind values but does not explicitly differentiate from sibling tools like get_docs or list_versions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to use each kind ('symbol' for API lookups, 'example' for code samples, 'auto' otherwise) and on version handling (omitting searches all versions, using version from hits for get_docs). No explicit when-not to use, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whatsnew_for_versionA
Read-onlyIdempotent

Browse indexed official What's New sections in document order.

Use kind to narrow the release topics. Sections are bounded; for full text use get_docs(slug='whatsnew/X.Y', version='X.Y', anchor=section.anchor). Pagination start_index counts nonempty sections after kind filtering.

NameRequiredDescriptionDefault
kindNo
versionYesPython version string, e.g. '3.11'
start_indexNoStart position for pagination
max_sectionsNoMaximum number of results to return.

Output Schema

NameRequiredDescription
sectionsNo
next_start_indexNo

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: sections are bounded (not full text), and pagination semantics ('start_index counts nonempty sections after kind filtering') explain a non-obvious counting rule. It does not mention truncation behavior when max_sections caps results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, each earning its place: purpose first, then filtering, then the escape hatch to get_docs, then pagination semantics. No redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return structure need not be explained. For a bounded, paginated, read-only browse tool, the description covers purpose, filtering, pagination counting, and the full-text alternative — everything an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, so the schema carries most parameter detail. The description still adds genuine meaning: 'kind' filters release topics, and the exact semantics of start_index (counting nonempty sections after filtering) are clarified in prose rather than left to the terse schema text. The version parameter is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Browse indexed official What's New sections in document order.' This is clearly distinct from generic doc tools, though the title is null and the description never explicitly says it is scoped to a single Python version (the required 'version' param implies it). Clear but not maximally sharp about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete guidance: use 'kind' to narrow release topics, and route to the alternative get_docs(slug='whatsnew/X.Y', ...) when full text is needed, with the exact anchor a caller would pass. It does not state exclusions versus search_docs or list_versions, but the primary alternative is named with a condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.4.0
    • Addedwhatsnew_for_version
  2. 1 tool updatev0.3.0
    • Addedcompare_versions
  3. 5 tool updatesv0.1.0
    • First observeddetect_python_version
    • First observedget_docs
    • First observedlist_versions
    • First observedlookup_package_docs
    • First observedsearch_docs
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.2/5.0

Scored across 7 tools

Disambiguation4/5

Each tool targets a distinct capability: retrieval (get_docs), search (search_docs), version listing/detection, cross-version diffing, What's New browsing, and PyPI metadata lookup. The only mild overlap is between whatsnew_for_version and get_docs with a whatsnew slug, but the description explicitly clarifies the boundary and defers full text to get_docs.

Naming Consistency4/5

Most tools follow a clean verb_noun snake_case pattern (compare_versions, detect_python_version, get_docs, list_versions, lookup_package_docs, search_docs). whatsnew_for_version deviates slightly in style but remains readable and self-explanatory.

Tool Count5/5

Seven tools is well-scoped for a documentation server, with each tool earning its place across the search/retrieve/compare/lookup workflow. No redundancy or bloat.

Completeness4/5

The surface covers the full docs lifecycle: discover versions, detect environment, search, retrieve sections, diff across versions, browse release notes, and resolve package docs URLs. Minor gaps like module/symbol enumeration exist, but agents can work around them via search_docs.

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Context7 MCP

    upstash
    A
    license
    A
    quality
    A
    maintenance
    A Model Context Protocol server that fetches up-to-date, version-specific documentation and code examples from libraries directly into LLM prompts, helping developers get accurate answers without outdated or hallucinated information.
    8
    2
    482,795 npm
    63,543
    MIT

  • devdocs-mcp

    madhan-g-p
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides version-pinned, deterministic documentation sourced from DevDocs.io to AI assistants (Claude, RooCode, Cline, Copilot etc.) and also via offline mode. Not via Scraping! But using the supported downloading option from devdocs.
    17 npm
    13
    MIT

  • Alcove

    epicsagas
    A
    license
    A
    quality
    B
    maintenance
    MCP server that gives AI coding agents on-demand access to private project docs via BM25 ranked search. One setup for Claude Code, Cursor, Codex, Gemini CLI, and more. Docs stay private, never in public repos.
    15
    16
    Apache 2.0