Skip to content

feat: lock positioning + rewrite hero around canonical-source framing #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ayhammouda merged 4 commits into from
May 14, 2026
+26 −8
Merged

feat: lock positioning + rewrite hero around canonical-source framing #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cf24fd4
docs: lock launch positioning sentence (decision 9.1)
ayhammouda May 14, 2026
d1fbfc5
docs(readme): rewrite hero around canonical-source positioning
ayhammouda May 14, 2026
14adf1c
docs: align glama/server/pyproject descriptions with locked positioning
ayhammouda May 14, 2026
25032b0
docs: soften POSITIONING verbatim claim + add token-frugal to PyPI su…
ayhammouda May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .planning/POSITIONING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# 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 (no rewording) in:**

- `README.md` hero
- 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.
9 changes: 3 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

<!-- mcp-name: io.github.ayhammouda/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](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)
Expand All @@ -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

Expand Down
1 change: 1 addition & 0 deletions glama.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.",
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use the locked positioning sentence verbatim in metadata.

Line 3 does not match the locked sentence wording/order (it rephrases with : and sentence split), so it fails the “verbatim across files” objective.

Suggested fix 
-  "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.",
+  "description": "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.",
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"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.",
"description": "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.",
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@glama.json` at line 3, The "description" value must exactly match the locked
positioning sentence; update the JSON entry for the "description" key so its
string is replaced verbatim with: For AI coding agents writing Python the
canonical Python stdlib oracle. Exact symbols, exact sections, exact versions —
offline, always free, always MIT, token-frugal. Ensure there are no added
punctuation, line breaks, or rephrasing (do this change in the "description"
field).

"maintainers": [
"ayhammouda"
]
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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, token-frugal."
readme = "README.md"
license = "MIT"
requires-python = ">=3.12"
Expand Down
2 changes: 1 addition & 1 deletion server.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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": {
Expand Down