From cf24fd439daf178bd58a3fbd68b45ad2ca1b5c13 Mon Sep 17 00:00:00 2001 From: Aymen Hammouda Date: Thu, 14 May 2026 13:37:19 +0200 Subject: [PATCH 1/4] docs: lock launch positioning sentence (decision 9.1) --- .planning/POSITIONING.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .planning/POSITIONING.md diff --git a/.planning/POSITIONING.md b/.planning/POSITIONING.md new file mode 100644 index 0000000..3ff248a --- /dev/null +++ b/.planning/POSITIONING.md @@ -0,0 +1,14 @@ +# Locked positioning (decision 9.1, locked 2026-05-14) + +**Sentence (verbatim):** + +> 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. + +**Use verbatim in:** + +- `README.md` hero +- `glama.json` `description` +- `server.json` `description` +- GitHub repo `About` text +- `LAUNCH-POST.md` lede +- Talk bio From d1fbfc51c804b26eece89d0b85505e7a675fa86b Mon Sep 17 00:00:00 2001 From: Aymen Hammouda Date: Thu, 14 May 2026 13:39:40 +0200 Subject: [PATCH 2/4] docs(readme): rewrite hero around canonical-source positioning Co-Authored-By: Claude Sonnet 4.6 --- README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 339f27d..2573ed7 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ +**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](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) [![Security Audit](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/security.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/security.yml) [![CodeQL](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/codeql.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/codeql.yml) @@ -13,12 +15,7 @@ [![No API Keys](https://img.shields.io/badge/API%20keys-none-success)](#why-use-it) [![Official Python Docs](https://img.shields.io/badge/source-official%20python%20docs-informational)](https://docs.python.org/3/) -`python-docs-mcp-server` is a read-only MCP server for the Python standard -library docs. It builds a local, version-aware index and gives MCP clients the -relevant section instead of a whole docs page. - -Use it with Claude, Cursor, Codex, or any MCP client when you want answers from -docs.python.org without API keys or a hosted docs API at query time. +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 From 14adf1c835d2e42afbf70bf7a1725da3408bcc66 Mon Sep 17 00:00:00 2001 From: Aymen Hammouda Date: Thu, 14 May 2026 13:43:07 +0200 Subject: [PATCH 3/4] docs: align glama/server/pyproject descriptions with locked positioning Co-Authored-By: Claude Sonnet 4.6 --- glama.json | 1 + pyproject.toml | 2 +- server.json | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/glama.json b/glama.json index 1b8ef1a..42643ae 100644 --- a/glama.json +++ b/glama.json @@ -1,5 +1,6 @@ { "$schema": "https://glama.ai/mcp/schemas/server.json", + "description": "For AI coding agents writing Python: the canonical Python stdlib oracle. Exact symbols, exact sections, exact versions — offline, always free, always MIT, token-frugal.", "maintainers": [ "ayhammouda" ] diff --git a/pyproject.toml b/pyproject.toml index d8fea7a..485971a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "python-docs-mcp-server" version = "0.1.4" -description = "A read-only, version-aware MCP retrieval server over Python standard library documentation" +description = "The canonical Python stdlib oracle for AI coding agents — exact symbols, exact sections, exact versions, offline, always free, always MIT." readme = "README.md" license = "MIT" requires-python = ">=3.12" diff --git a/server.json b/server.json index decd018..d5542bd 100644 --- a/server.json +++ b/server.json @@ -1,7 +1,7 @@ { "$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.", + "description": "The canonical Python stdlib oracle for AI coding agents. Exact symbols, exact sections, exact versions — offline, always free, always MIT, token-frugal.", "title": "Python Docs MCP Server", "websiteUrl": "https://github.com/ayhammouda/python-docs-mcp-server", "repository": { From 25032b07056a0075bc6300ffa93e5e8133d08a66 Mon Sep 17 00:00:00 2001 From: Aymen Hammouda Date: Thu, 14 May 2026 16:09:16 +0200 Subject: [PATCH 4/4] docs: soften POSITIONING verbatim claim + add token-frugal to PyPI summary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-AI review (Codex P3) caught that .planning/POSITIONING.md claimed 'Use verbatim in: glama.json / server.json' while the actual descriptions deliberately vary by surface (long marketing form vs medium vs PyPI-short). Fix: split into two lists — surfaces that use the sentence verbatim (README hero, GitHub About, launch post, talk bio) vs surfaces that adapt for length but preserve the three key phrases. Also: add 'token-frugal' to pyproject.toml description so all four machine-read positioning surfaces carry the full anchor consistently. Prior Claude reviewer had flagged this as deferrable to PR #3; folding it in here makes POSITIONING.md's new 'preserve all three key phrases' contract internally consistent. Char count: pyproject.toml description = 154 chars (under PyPI's 512 limit). Key-phrase coverage verified: 3 phrases x 4 surfaces = 12/12 present. --- .planning/POSITIONING.md | 12 +++++++++--- pyproject.toml | 2 +- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/.planning/POSITIONING.md b/.planning/POSITIONING.md index 3ff248a..4a50eb2 100644 --- a/.planning/POSITIONING.md +++ b/.planning/POSITIONING.md @@ -4,11 +4,17 @@ > 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. -**Use verbatim in:** +**Use verbatim (no rewording) in:** - `README.md` hero -- `glama.json` `description` -- `server.json` `description` - GitHub repo `About` text - `LAUNCH-POST.md` lede - Talk bio + +**Adapt for length and grammar in (preserve key phrases: `canonical Python stdlib oracle`, `always free, always MIT`, `token-frugal`):** + +- `glama.json` `description` — long marketing form (Glama directory display) +- `server.json` `description` — medium form (MCP Registry display) +- `pyproject.toml` `description` — short form (PyPI summary, ≤512 chars) + +The locked sentence is the anchor; adapted forms must keep the three key phrases and the wedge claim (canonical / version-aware / offline). They may drop "exact symbols, exact sections, exact versions" for brevity if needed, but never the three anchors above. diff --git a/pyproject.toml b/pyproject.toml index 485971a..2443441 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "python-docs-mcp-server" version = "0.1.4" -description = "The canonical Python stdlib oracle for AI coding agents — exact symbols, exact sections, exact versions, offline, always free, always MIT." +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" requires-python = ">=3.12"