python-docs-mcp-server 0.3.0__tar.gz → 0.3.1__tar.gz

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/.github/workflows/ci.yml

@@ -18,10 +18,10 @@ jobs:
     name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
         with:
           cache-suffix: py${{ matrix.python-version }}
 

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/.github/workflows/codeql.yml

@@ -22,7 +22,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v4

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/.github/workflows/e2e.yml

@@ -17,10 +17,10 @@ jobs:
         python-version: ["3.13", "3.14"]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
         with:
           cache-suffix: py${{ matrix.python-version }}
 

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/.github/workflows/release.yml

@@ -16,10 +16,10 @@ jobs:
     timeout-minutes: 15
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
 
       - name: Set up Python 3.13
         run: uv python install 3.13
@@ -117,7 +117,7 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install mcp-publisher
         run: |

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/.github/workflows/scorecard.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           persist-credentials: false
 

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/.github/workflows/security.yml

@@ -20,10 +20,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
 
       - name: Export locked dependencies
         run: |

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/.gitignore

@@ -194,6 +194,9 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 
+# Local planning / agent workspace
+.planning/
+
 # Cursor
 #  Keep repo-local Cursor context files tracked when present so the repository
 #  can define its own indexing boundaries.

python_docs_mcp_server-0.3.1/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "python-docs": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["python-docs-mcp-server"]
+    }
+  }
+}

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `python-docs-mcp-server` are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] — 2026-06-01
+
+### Added
+
+- Added a checked-in `.mcp.json` project configuration for MCP clients that
+  support project-scoped server config. It starts the published server with
+  `uvx python-docs-mcp-server`.
+
+### Changed
+
+- Bumped package and MCP Registry metadata to `0.3.1`.
+
 ## [0.3.0] — 2026-05-31
 
 ### Added

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-docs-mcp-server
-Version: 0.3.0
+Version: 0.3.1
 Summary: The canonical Python stdlib oracle for AI coding agents — exact symbols, exact sections, exact versions, offline, always free, always MIT, token-frugal.
 Author-email: Aymen Hammouda <hammouda.aymen@gmail.com>
 License-Expression: MIT
@@ -48,6 +48,13 @@ Built for the moment your agent needs `asyncio.TaskGroup` signatures, `pathlib.P
 
 ## Why this exists
 
+There is a difference between long context and usable context. Research like the
+[*Lost in the Middle*](https://arxiv.org/abs/2307.03172) 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
@@ -140,6 +147,26 @@ cache. It can take several minutes.
 
 ## 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:
+
+```json
+{
+  "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:

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/README.md

@@ -19,6 +19,13 @@ Built for the moment your agent needs `asyncio.TaskGroup` signatures, `pathlib.P
 
 ## Why this exists
 
+There is a difference between long context and usable context. Research like the
+[*Lost in the Middle*](https://arxiv.org/abs/2307.03172) 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
@@ -111,6 +118,26 @@ cache. It can take several minutes.
 
 ## 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:
+
+```json
+{
+  "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:

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/STRATEGIC-ROADMAP-2026-05-29.md

@@ -161,6 +161,9 @@ Consolidated from prior artifacts and this consolidation.
 | 5.12 | Autonomous agents work only via the issue-and-PR flow defined in `AGENT-EXECUTION-PIPELINE.md`. Direct commits to `main` are forbidden; Vision-owned merge is required. | Agent-pipeline addition (2026-05-29) |
 | 5.13 | Forbidden-territory list in `AGENT-EXECUTION-PIPELINE.md` §2 is binding on all agents. | Agent-pipeline addition (2026-05-29) |
 | 5.14 | Every agent-targetable issue must have a per-issue context file under `.planning/agent-context/<issue-slug>.md`. | Agent-pipeline addition (2026-05-29) |
+| 5.15 | *Lost in the Middle* (Liu et al., 2023, arXiv:2307.03172) is the canonical external citation for the "long context is unreliable; precise retrieval is the antidote" framing. Used as motivation only (README / positioning / launch); never presented as this project's own benchmark. | Amendment 2026-06-01 |
+| 5.16 | Positioning discipline: **tokens are the business problem; bytes are an implementation detail.** Public-facing copy leads with precise retrieval, version-accuracy, and token economy. Byte-level compression (zstd cache, decision 5.7) is an engineering footnote, never a headline. Reinforces 2.4, 2.5, 5.7. | Amendment 2026-06-01 |
+| 5.17 | Evidence ladder: no comparative or benchmark claim ships in public copy until the v0.5.0 public benchmark harness produces reproducible data with methodology disclosure. The v0.3.0 empirical token study (Study A) stays internal and only gates the `format="toon"` decision. | Amendment 2026-06-01 |
 
 ---
 
@@ -269,3 +272,23 @@ This roadmap is reviewed at:
 - Owner's discretion when new external information arrives (e.g., another deep-research report; a sufficiently sharp critique from the community).
 
 Out-of-cycle amendments are tracked at the bottom of this file as `## Amendment YYYY-MM-DD` sections, preserving the original text. The locked-decisions table (§5) is the authoritative current state.
+
+---
+
+## Amendment 2026-06-01
+
+**Trigger:** Owner's discretion (§10) — advisory review of how the project frames *evidence* in public-facing copy.
+
+This amendment records a three-layer separation of evidence that public and internal materials must respect, plus the positioning discipline that follows from it. It adds locked decisions 5.15–5.17 (see §5).
+
+### Three layers of evidence (do not conflate)
+
+1. **External citation — use now.** *Lost in the Middle* (Liu et al., 2023, arXiv:2307.03172) is research about a failure mode: models use information poorly when it is buried in a long context. It motivates the *problem* — long context is not automatically usable context — and is cited as motivation only, never as our own measurement. (Decision 5.15.)
+2. **Internal study (Study A) — gates an engineering choice.** The v0.3.0 empirical token study measures real token cost and latency after client-side rewrap (decision 5.8) and gates whether `format="toon"` ships (decisions 5.4, 5.5; ADR-006). It stays internal and produces no public comparative claim. (Decision 5.17.)
+3. **Public benchmark (Study B) — sells the project later.** The v0.5.0 public benchmark harness (§4 v0.5.0) compares this server against eligible docs MCPs and a no-MCP baseline on correctness, tokens, and latency — reproducible from a clean clone, with mandatory methodology disclosure. It is the only artifact licensed to make a comparative claim, and only once it has data. (Decision 5.17; tracked as a GitHub issue.)
+
+### Positioning discipline
+
+Tokens are the business problem; bytes are an implementation detail. Public copy (README / PyPI / glama / launch) leads with precise retrieval, version-accuracy, and token economy. The zstd retrieved-docs cache (decision 5.7) is cache-at-rest only and stays an engineering footnote — it never becomes a headline selling point. (Decision 5.16.)
+
+This discipline also supersedes the need for a separate note in the now-local-only `.planning/POSITIONING.md`: `.planning/` is no longer tracked on `main` (see `chore: ignore local planning workspace`), so the discipline lives here, in the tracked roadmap, rather than in the planning workspace.

python_docs_mcp_server-0.3.1/docs/benchmarks/PUBLIC-BENCHMARK-METHODOLOGY.md

@@ -0,0 +1,221 @@
+# Public Benchmark Methodology
+
+**Status:** Draft methodology for issue
+[#63](https://github.com/ayhammouda/python-docs-mcp-server/issues/63).
+Do not publish comparative claims until the harness has produced reproducible
+data from this methodology.
+
+## Purpose
+
+The v0.5.0 public benchmark compares `python-docs-mcp-server` with eligible
+Python documentation MCPs and a no-MCP baseline on a fixed 50-question Python
+documentation evaluation. The benchmark reports correctness, token cost, and
+latency, with enough detail for a clean clone to reproduce the run.
+
+This is an evidence artifact, not marketing copy. If the data is boring or
+unfavorable, publish the data honestly and adjust the product claims.
+
+## Evidence Flow
+
+```mermaid
+flowchart LR
+    Corpus[50-question corpus] --> Runner[Benchmark runner]
+    Competitors[Pinned MCP competitors] --> Runner
+    Baseline[No-MCP baseline] --> Runner
+    Runner --> Transcripts[Raw transcripts]
+    Transcripts --> Tokens[Token counting after client rewrap]
+    Transcripts --> Rubric[Correctness scoring]
+    Transcripts --> Latency[Latency summary]
+    Tokens --> Report[Public report]
+    Rubric --> Report
+    Latency --> Report
+```
+
+## Systems Under Test
+
+The final competitor set is locked at execution time. A competitor is eligible
+only if all of these are true:
+
+- It exposes Python standard library documentation retrieval or search.
+- It can be run or queried reproducibly from a clean clone.
+- Its version, package, image, endpoint, or commit can be pinned.
+- Its terms allow benchmark use.
+- It does not require private, undocumented access.
+
+The initial candidate matrix is:
+
+- `python-docs-mcp-server`
+- Context7
+- GitMCP
+- DeepWiki
+- Ref.tools
+- no-MCP baseline
+
+The no-MCP baseline uses the same model and question prompts, but no retrieved
+documentation context. It measures parametric model behavior, not another docs
+tool.
+
+## Corpus Design
+
+The corpus contains exactly 50 questions. Each question must include:
+
+- Stable question ID.
+- Category.
+- Python version or version pair.
+- Prompt shown to the model.
+- Official-docs answer key.
+- Required citations or source sections.
+- Expected answer properties.
+- Known ambiguity notes, if any.
+
+Distribution:
+
+- 15 exact-symbol questions.
+- 10 concept or API-usage questions.
+- 15 cross-version questions, led by `compare_versions`-style diffs.
+- 5 PEP-adjacent questions where the official stdlib docs or "What's New"
+  pages contain the required answer.
+- 5 applied questions that require selecting the right stdlib API from the
+  documentation.
+
+The corpus must avoid questions whose answer requires private knowledge,
+external package documentation, non-stdlib behavior, or unreleased CPython
+changes.
+
+## Source Of Truth
+
+Correctness is scored against official Python documentation generated from
+CPython source at pinned tags. When a question concerns version behavior, the
+answer key must cite the exact relevant version or version pair.
+
+Allowed truth sources:
+
+- CPython documentation source at pinned commit or tag.
+- Generated official docs for the same Python version.
+- Official "What's New" pages for PEP-adjacent behavior.
+
+Disallowed truth sources:
+
+- Blog posts.
+- Search snippets.
+- LLM-generated explanations.
+- Third-party mirrors unless used only as a convenience link and verified
+  against CPython source.
+
+## Prompting Rules
+
+Every system under test receives the same user question. The only allowed
+difference is the documentation context supplied by that system.
+
+The model prompt must require:
+
+- A concise answer.
+- Version-specific wording when the question names a version.
+- No unsupported claims.
+- A short citation to the retrieved section when the system provides one.
+
+The prompt must not reveal the answer key, rubric, or expected winning system.
+
+## Correctness Scoring
+
+Each answer receives one score:
+
+- `1.0`: Correct, version-aware, and includes all required answer properties.
+- `0.5`: Partially correct, but misses a required nuance, version condition, or
+  citation.
+- `0.0`: Incorrect, unsupported, materially incomplete, or answers the wrong
+  version.
+
+For public reporting, include both:
+
+- Mean correctness score.
+- Per-category correctness score.
+
+Any answer that appears correct but lacks evidence from the supplied docs is
+marked in the raw results and discussed separately. The benchmark should reward
+grounded answers, not confident autocomplete.
+
+## Token Measurement
+
+Token methodology follows roadmap decision 5.8 and ADR-006:
+
+- Use Claude token counting as the primary metric.
+- Measure after client-side rewrap, not only raw MCP payload bytes.
+- Record raw payload tokens separately as diagnostic data.
+- Report serialization latency alongside token counts.
+
+Primary token count:
+
+1. Capture the MCP tool response or baseline prompt context.
+2. Pass it through the same client-side wrapping path used by the benchmark
+   client.
+3. Count the resulting message envelope with Claude token counting.
+
+If a client cannot expose its exact wrapped message envelope, the report must
+say so and mark that result as an approximation. Approximate counts must not be
+used for headline claims.
+
+## Latency Measurement
+
+Latency is wall-clock time measured per question from request dispatch to final
+answer receipt.
+
+Report:
+
+- Median.
+- p95.
+- Minimum and maximum.
+- Cold-run and warm-run separation where the system has a cache or index.
+
+Index build time is not part of per-query latency. It may be reported as setup
+cost in a separate section.
+
+## Reproducibility
+
+The public harness must run from a clean clone with one command after dependency
+installation. It must write:
+
+- Competitor manifest with pinned versions.
+- Corpus file.
+- Raw transcripts.
+- Raw scoring records.
+- Token-count records.
+- Latency records.
+- Summary report.
+
+Result files must include enough metadata to rerun or audit them:
+
+- Repository commit.
+- Python version.
+- Operating system.
+- Model name and provider.
+- MCP client or adapter version.
+- Competitor versions.
+- Timestamp.
+
+## Honesty Rules
+
+- No comparative claim enters README, PyPI, launch copy, or social posts before
+  public results exist.
+- Do not drop failed systems silently. If a competitor cannot run, report the
+  failure reason and exclude it from scored comparisons.
+- Do not change the corpus after seeing results unless the change is documented
+  and the whole benchmark is rerun.
+- Do not tune prompts per competitor.
+- Do not report approximate token counts as exact.
+
+## Harness Work Packages
+
+Once this methodology is accepted, the implementation can be split into smaller
+agent-ready issues:
+
+1. Corpus schema and fixture loader.
+2. Baseline runner and transcript format.
+3. `python-docs-mcp-server` runner.
+4. Competitor manifest and adapter skeletons.
+5. Correctness scorer with manual-adjudication hooks.
+6. Claude token-count integration after client rewrap.
+7. Latency recorder and report generator.
+
+Each work package should reference this methodology and use `Refs #63`, not
+`Closes #63`, until the full benchmark has produced public data.

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-docs-mcp-server"
-version = "0.3.0"
+version = "0.3.1"
 description = "The canonical Python stdlib oracle for AI coding agents — exact symbols, exact sections, exact versions, offline, always free, always MIT, token-frugal."
 readme = "README.md"
 license = "MIT"

{python_docs_mcp_server-0.3.0 → python_docs_mcp_server-0.3.1}/server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/ayhammouda/python-docs-mcp-server",
     "source": "github"
   },
-  "version": "0.3.0",
+  "version": "0.3.1",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "python-docs-mcp-server",
-      "version": "0.3.0",
+      "version": "0.3.1",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"