From 32405f01766c3d05caffd0b895869dbef052cfaf Mon Sep 17 00:00:00 2001 From: "bluecloud-gilfoyle[bot]" <262642412+bluecloud-gilfoyle[bot]@users.noreply.github.com> Date: Sat, 9 May 2026 11:45:21 +0000 Subject: [PATCH 1/2] chore: prepare autonomous launch pack --- .github/RELEASE.md | 30 ++++++++--------- README.md | 67 ++++++++++++++++++++++++++++--------- docs/launch/reddit-posts.md | 67 +++++++++++++++++++++++++++++++++++++ docs/launch/show-hn.md | 39 +++++++++++++++++++++ server.json | 30 +++++++++++++++++ 5 files changed, 202 insertions(+), 31 deletions(-) create mode 100644 docs/launch/reddit-posts.md create mode 100644 docs/launch/show-hn.md create mode 100644 server.json diff --git a/.github/RELEASE.md b/.github/RELEASE.md index 7d42e4f..16d06e8 100644 --- a/.github/RELEASE.md +++ b/.github/RELEASE.md @@ -41,20 +41,20 @@ versions 3.10 through 3.14. 2. Verify the version in `pyproject.toml` is correct: ```bash grep '^version' pyproject.toml - # Should show: version = "0.1.0" + # Should show: version = "0.1.1" ``` 3. Create and push the tag: ```bash - git tag -a v0.1.0 -m "Release v0.1.0" - git push origin v0.1.0 + git tag -a v0.1.1 -m "Release v0.1.1" + git push origin v0.1.1 ``` 4. Monitor the release workflow at: https://github.com//python-docs-mcp-server/actions/workflows/release.yml 5. Verify the package on PyPI: - https://pypi.org/project/mcp-server-python-docs/0.1.0/ + https://pypi.org/project/mcp-server-python-docs/0.1.1/ ## Post-Release Verification @@ -63,14 +63,14 @@ After the package is published: ```bash # In a fresh environment: uvx mcp-server-python-docs --version -# Should print: 0.1.0 +# Should print: 0.1.1 # Or via pipx: pipx run mcp-server-python-docs --version -# Should print: 0.1.0 +# Should print: 0.1.1 ``` -## v0.1.0 Release Checklist +## v0.1.1 Release Checklist Complete these steps in order. Each step has a checkbox -- do not skip ahead. @@ -81,7 +81,7 @@ Complete these steps in order. Each step has a checkbox -- do not skip ahead. ```bash uv run pytest --tb=short -q ``` -- [ ] Version in `pyproject.toml` is `0.1.0`: +- [ ] Version in `pyproject.toml` is `0.1.1`: ```bash grep '^version' pyproject.toml ``` @@ -105,7 +105,7 @@ Complete these steps in order. Each step has a checkbox -- do not skip ahead. - [ ] Create the annotated tag: ```bash - git tag -a v0.1.0 -m "Release v0.1.0 + git tag -a v0.1.1 -m "Release v0.1.1 First public release of mcp-server-python-docs. @@ -116,14 +116,14 @@ Complete these steps in order. Each step has a checkbox -- do not skip ahead. ``` - [ ] Push the tag to trigger the release workflow: ```bash - git push origin v0.1.0 + git push origin v0.1.1 ``` - [ ] Monitor the workflow run: https://github.com//python-docs-mcp-server/actions/workflows/release.yml - [ ] Verify all three jobs pass: `build` -> `publish` -> `github-release` ### Post-Release Verification (SHIP-06) -- [ ] Package visible on PyPI: https://pypi.org/project/mcp-server-python-docs/0.1.0/ +- [ ] Package visible on PyPI: https://pypi.org/project/mcp-server-python-docs/0.1.1/ - [ ] Attestation visible on PyPI package page (look for "Provenance" badge) - [ ] Fresh install test: ```bash @@ -132,13 +132,13 @@ Complete these steps in order. Each step has a checkbox -- do not skip ahead. # Install and verify version uvx mcp-server-python-docs --version - # Expected output: 0.1.0 + # Expected output: 0.1.1 ``` - [ ] Full README flow test (from a clean environment): ```bash # Step 1: Install uvx mcp-server-python-docs --version - # Should print 0.1.0 + # Should print 0.1.1 # Step 2: Build index uvx mcp-server-python-docs build-index --versions 3.10,3.11,3.12,3.13,3.14 @@ -161,10 +161,10 @@ Complete these steps in order. Each step has a checkbox -- do not skip ahead. ### Release Complete - [ ] GitHub Release exists with attached artifacts -- [ ] PyPI page shows 0.1.0 with attestation +- [ ] PyPI page shows 0.1.1 with attestation - [ ] README install instructions verified end-to-end - [ ] Slow E2E workflow passed for the release candidate -- [ ] Tag v0.1.0 exists in git +- [ ] Tag v0.1.1 exists in git **Release date**: _______________ **Released by**: _______________ diff --git a/README.md b/README.md index 0e4dec6..e22a2fd 100644 --- a/README.md +++ b/README.md @@ -58,9 +58,33 @@ exposes a small MCP tool surface tuned for high-signal retrieval. The model gets the exact symbol match and the relevant documentation section instead of 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? + +The agent 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 +the official stdlib text for the requested Python version, trimmed to the useful +section. + +Local source smoke test until the PyPI package is published: + +```bash +uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs --version +``` + ## Install -Run it directly with `uvx`: +Until the first PyPI release is published, run from GitHub: + +```bash +uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs --version +``` + +After PyPI publishing is complete, the package will also run directly with +`uvx`: ```bash uvx mcp-server-python-docs --version @@ -80,9 +104,11 @@ shell or use `python -m uv ...` as a fallback for local contributor commands. Build the local documentation index: ```bash -uvx mcp-server-python-docs build-index --versions 3.10,3.11,3.12,3.13,3.14 +uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs build-index --versions 3.10,3.11,3.12,3.13,3.14 ``` +After PyPI publishing, `uvx mcp-server-python-docs build-index ...` is enough. + If you installed the package persistently, you can drop the `uvx` prefix: ```bash @@ -110,7 +136,11 @@ Add this to your Claude Desktop configuration file: "mcpServers": { "python-docs": { "command": "uvx", - "args": ["mcp-server-python-docs"] + "args": [ + "--from", + "git+https://github.com/ayhammouda/python-docs-mcp-server.git", + "mcp-server-python-docs" + ] } } } @@ -128,7 +158,11 @@ global settings): "mcpServers": { "python-docs": { "command": "uvx", - "args": ["mcp-server-python-docs"] + "args": [ + "--from", + "git+https://github.com/ayhammouda/python-docs-mcp-server.git", + "mcp-server-python-docs" + ] } } } @@ -141,7 +175,7 @@ Add this to `.codex/config.toml`: ```toml [mcp_servers.python-docs] command = "uvx" -args = ["mcp-server-python-docs"] +args = ["--from", "git+https://github.com/ayhammouda/python-docs-mcp-server.git", "mcp-server-python-docs"] ``` ## How quality is verified @@ -174,20 +208,21 @@ The server currently exposes five MCP tools: | `list_versions` | List all indexed Python versions with metadata. | | `detect_python_version` | Detect the user's local Python version and report whether it matches an indexed documentation version. | -## When to use this instead of generic docs retrieval - -Use this server when you need: +## Why not Context7 or generic docs retrieval? -- exact Python stdlib symbol resolution -- consistent version-aware answers across Python 3.10 through 3.14 -- token-efficient section retrieval from official docs -- a local, read-only MCP server with a simple operational story +Use this server when the question is about Python's standard library and you +want the boring answer that is actually correct: -Use a generic fetcher or broader docs MCP when you need: +- official Python docs, not scraped mirrors or mixed-source summaries +- exact symbol resolution from `objects.inv` +- Python-version-aware results across 3.10 through 3.14 +- token-efficient section retrieval instead of full-page dumps +- local, read-only runtime behavior with no API keys -- arbitrary third-party package content beyond package-declared PyPI metadata -- arbitrary web pages -- mixed-source research across many frameworks +Use Context7 or a generic docs fetcher when you need broader third-party library +coverage, arbitrary web pages, or cross-framework research. This server is not a +universal docs search engine. It is a precise stdlib retrieval tool for AI +coding agents. ## Retrieved docs cache diff --git a/docs/launch/reddit-posts.md b/docs/launch/reddit-posts.md new file mode 100644 index 0000000..94e7faf --- /dev/null +++ b/docs/launch/reddit-posts.md @@ -0,0 +1,67 @@ +# Reddit launch drafts + +Do not post these until the package is published on PyPI and the release smoke +test passes. Until then, use the GitHub `uvx --from git+...` install command. + +## r/Python + +Title: I built a local MCP server for official Python stdlib docs + +I built `mcp-server-python-docs`, a small read-only MCP server that gives AI +coding agents access to the official Python standard library docs. + +Why I wanted it: + +- exact stdlib symbol lookup via Python `objects.inv` +- version-aware answers for Python 3.10 through 3.14 +- section-level retrieval instead of dumping whole pages into context +- local SQLite/FTS index, no runtime web scraping, no API keys +- read-only MCP tools, so the operational/security story is boring + +Example use case: ask an agent about `asyncio.TaskGroup` in Python 3.13 and it +can retrieve the exact official docs section instead of guessing from generic web +results. + +Repo: https://github.com/ayhammouda/python-docs-mcp-server + +Current note: PyPI publishing is still being finalized. For now, test from +source: + +```bash +uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs --version +``` + +Feedback welcome, especially on retrieval quality, MCP client setup, and which +stdlib docs workflows feel clunky in real use. + +## r/LocalLLaMA + +Title: Local MCP server for official Python docs, built for coding agents + +I made a local MCP server for Python standard library documentation. It builds a +local index from the official docs and exposes small read-only tools for search +and section retrieval. + +The goal is not to be a universal docs search engine. It is the opposite: a +boring, precise source for Python stdlib questions where version matters and +tokens are limited. + +What it does: + +- official Python docs only for stdlib retrieval +- Python-version-aware results across 3.10-3.14 +- exact symbol lookup from `objects.inv` +- local SQLite + FTS5 index +- no API keys or hosted retrieval dependency at query time + +Repo: https://github.com/ayhammouda/python-docs-mcp-server + +PyPI publishing is not done yet, so don't use the plain `uvx` package command +until that lands. Source install smoke test: + +```bash +uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs --version +``` + +I'd appreciate practical feedback from people wiring MCP into local coding +workflows. diff --git a/docs/launch/show-hn.md b/docs/launch/show-hn.md new file mode 100644 index 0000000..5d1e2ee --- /dev/null +++ b/docs/launch/show-hn.md @@ -0,0 +1,39 @@ +# Show HN launch draft + +Do not submit until PyPI publishing is complete and the release smoke test passes. + +## Title + +Show HN: Local MCP server for official Python standard library docs + +## Post + +Hi HN — I built `mcp-server-python-docs`, a read-only MCP server that gives AI +coding agents precise access to the official Python standard library docs. + +The motivation: generic docs retrieval is often noisy for stdlib questions. +Python answers are sensitive to exact symbols and versions, and agents do not +need a whole docs page when one section answers the question. + +What it does: + +- builds a local SQLite/FTS index from official Python docs +- resolves exact symbols from Python `objects.inv` +- retrieves section-level docs with truncation and pagination +- supports version-aware lookup across Python 3.10 through 3.14 +- runs locally, read-only, with no API keys + +It is intentionally narrow. Use Context7 or generic retrieval for broad +third-party docs and web research. Use this when you want official stdlib docs +with less token waste. + +Repo: https://github.com/ayhammouda/python-docs-mcp-server + +PyPI publishing is still pending. Until that is finished, test from GitHub: + +```bash +uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs --version +``` + +I'd love feedback on the MCP interface, retrieval output, and whether the local +indexing flow is clear enough. diff --git a/server.json b/server.json new file mode 100644 index 0000000..2e8c906 --- /dev/null +++ b/server.json @@ -0,0 +1,30 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.ayhammouda/python-docs-mcp-server", + "description": "Local, read-only MCP retrieval over official Python standard library docs.", + "title": "Python Docs MCP Server", + "websiteUrl": "https://github.com/ayhammouda/python-docs-mcp-server", + "repository": { + "url": "https://github.com/ayhammouda/python-docs-mcp-server", + "source": "github" + }, + "version": "0.1.1", + "packages": [ + { + "registryType": "pypi", + "registryBaseUrl": "https://pypi.org", + "identifier": "mcp-server-python-docs", + "version": "0.1.1", + "runtimeHint": "uvx", + "transport": { + "type": "stdio" + } + } + ], + "_meta": { + "io.modelcontextprotocol.registry/publisher-provided": { + "status": "ready-for-validation-after-pypi-publish", + "notes": "PyPI package metadata is included for the official MCP Registry, but package publication is tracked separately." + } + } +} From 8c6651af84be024222f44c0ce48c72909357fd9b Mon Sep 17 00:00:00 2001 From: Aymen Hammouda Date: Sun, 10 May 2026 23:51:40 +0200 Subject: [PATCH 2/2] docs: prepare launch pack for PyPI validation --- README.md | 44 ++++++++++++++++++++++++++++++++++++--- docs/launch/show-hn.md | 47 +++++++++++++++++++++++++++++++++++++----- 2 files changed, 83 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index e22a2fd..419fbdc 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # mcp-server-python-docs + + [![CI](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/) @@ -71,17 +73,21 @@ section. Local source smoke test until the PyPI package is published: + ```bash uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs --version ``` + ## Install Until the first PyPI release is published, run from GitHub: + ```bash uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs --version ``` + After PyPI publishing is complete, the package will also run directly with `uvx`: @@ -103,9 +109,11 @@ shell or use `python -m uv ...` as a fallback for local contributor commands. Build the local documentation index: + ```bash uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs build-index --versions 3.10,3.11,3.12,3.13,3.14 ``` + After PyPI publishing, `uvx mcp-server-python-docs build-index ...` is enough. @@ -131,6 +139,7 @@ Add this to your Claude Desktop configuration file: **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json` + ```json { "mcpServers": { @@ -145,6 +154,7 @@ Add this to your Claude Desktop configuration file: } } ``` + Restart Claude Desktop after editing the config file. @@ -153,6 +163,7 @@ Restart Claude Desktop after editing the config file. Add this to your Cursor MCP settings (`.cursor/mcp.json` in your project or global settings): + ```json { "mcpServers": { @@ -167,16 +178,19 @@ global settings): } } ``` + ### Codex Add this to `.codex/config.toml`: + ```toml [mcp_servers.python-docs] command = "uvx" args = ["--from", "git+https://github.com/ayhammouda/python-docs-mcp-server.git", "mcp-server-python-docs"] ``` + ## How quality is verified @@ -258,7 +272,15 @@ search, or silently fall back to unofficial community mirrors. ## Diagnostics -Check the local environment: +Before PyPI publishing, run `doctor` from the GitHub source package: + + +```bash +uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs doctor +``` + + +After PyPI publishing: ```bash uvx mcp-server-python-docs doctor @@ -268,7 +290,17 @@ This checks the runtime Python version, SQLite FTS5, cache/index paths, disk space, and whether the current interpreter has the `venv`/`ensurepip` support needed by `build-index`. -Validate an existing index: +Validate an existing index. + +Before PyPI publishing: + + +```bash +uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-server-python-docs validate-corpus +``` + + +After PyPI publishing: ```bash uvx mcp-server-python-docs validate-corpus @@ -282,6 +314,9 @@ If you see an error about SQLite FTS5 not being available: **Linux x86-64** +After PyPI publishing, Linux x86-64 users can install the optional bundled +SQLite package: + ```bash pip install 'mcp-server-python-docs[pysqlite3]' ``` @@ -309,7 +344,7 @@ JSON documentation content. ### `uvx` cache stale -If `uvx mcp-server-python-docs` runs an old version: +After PyPI publishing, if `uvx mcp-server-python-docs` runs an old version: ```bash uvx --reinstall mcp-server-python-docs @@ -362,6 +397,9 @@ every release. Python documentation versions 3.10 through 3.14 are currently supported. +The server requires Python 3.12+ to run. Its generated documentation corpus can +still index Python documentation versions 3.10 through 3.14. + ## License MIT diff --git a/docs/launch/show-hn.md b/docs/launch/show-hn.md index 5d1e2ee..27c9456 100644 --- a/docs/launch/show-hn.md +++ b/docs/launch/show-hn.md @@ -1,14 +1,17 @@ # Show HN launch draft -Do not submit until PyPI publishing is complete and the release smoke test passes. +Use the pre-PyPI draft for private feedback only. Submit the post-PyPI draft to +HN only after PyPI publishing is complete and the release smoke test passes. -## Title +## Pre-PyPI feedback draft -Show HN: Local MCP server for official Python standard library docs +### Title + +Feedback: Local MCP server for official Python standard library docs -## Post +### Post -Hi HN — I built `mcp-server-python-docs`, a read-only MCP server that gives AI +Hi HN -- I built `mcp-server-python-docs`, a read-only MCP server that gives AI coding agents precise access to the official Python standard library docs. The motivation: generic docs retrieval is often noisy for stdlib questions. @@ -37,3 +40,37 @@ uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git mcp-serv I'd love feedback on the MCP interface, retrieval output, and whether the local indexing flow is clear enough. + +## Post-PyPI Show HN draft + +### Title + +Show HN: Local MCP server for official Python standard library docs + +### Post + +Hi HN -- I built `mcp-server-python-docs`, a read-only MCP server that gives AI +coding agents precise access to the official Python standard library docs. + +The motivation: generic docs retrieval is often noisy for stdlib questions. +Python answers are sensitive to exact symbols and versions, and agents do not +need a whole docs page when one section answers the question. + +What it does: + +- builds a local SQLite/FTS index from official Python docs +- resolves exact symbols from Python `objects.inv` +- retrieves section-level docs with truncation and pagination +- supports version-aware lookup across Python 3.10 through 3.14 +- runs locally, read-only, with no API keys + +Repo: https://github.com/ayhammouda/python-docs-mcp-server + +Install after the PyPI release: + +```bash +uvx mcp-server-python-docs --version +``` + +I'd love feedback on the MCP interface, retrieval output, and whether the local +indexing flow is clear enough.