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..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/) @@ -58,9 +60,37 @@ 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 @@ -79,9 +109,13 @@ 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: @@ -105,16 +139,22 @@ Add this to your Claude Desktop configuration file: **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json` + ```json { "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" + ] } } } ``` + Restart Claude Desktop after editing the config file. @@ -123,26 +163,34 @@ 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": { "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" + ] } } } ``` + ### Codex 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 +222,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 +## Why not Context7 or generic docs retrieval? -Use this server when you need: +Use this server when the question is about Python's standard library and you +want the boring answer that is actually correct: -- 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 +- 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 -Use a generic fetcher or broader docs MCP when you need: - -- 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 @@ -223,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 @@ -233,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 @@ -247,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]' ``` @@ -274,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 @@ -327,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/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..27c9456 --- /dev/null +++ b/docs/launch/show-hn.md @@ -0,0 +1,76 @@ +# Show HN launch draft + +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. + +## Pre-PyPI feedback draft + +### Title + +Feedback: 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. + +## 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. 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." + } + } +}