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
Merged

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

Show file tree
Hide file tree
Changes from 3 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
14 changes: 14 additions & 0 deletions .planning/POSITIONING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

@coderabbitai coderabbitai Bot May 14, 2026

Copy link
Copy Markdown

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

Avoid normative “source-of-truth” directives in .planning/.

Lines 7–14 are written as enforceable policy (“Use verbatim in”), which conflicts with the rule that .planning/ is archival history, not live truth. Rephrase this section as a historical record (e.g., “Applied in … on 2026-05-14”) and keep enforcement in live docs/checks.

As per coding guidelines, ".planning/**: Treat .planning/ directory as archival project history, not live repo truth".

🤖 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 @.planning/POSITIONING.md around lines 7 - 14, The section starting with the
heading "Use verbatim in:" and its bullet list (the lines listing README.md
hero, glama.json description, server.json description, GitHub repo About text,
LAUNCH-POST.md lede, Talk bio) reads like an enforceable policy; change it to a
historical/archival statement instead (e.g., "Applied in README.md, glama.json,
server.json, GitHub About, LAUNCH-POST.md, and Talk bio on 2026-05-14") and
remove language that prescribes current enforcement; keep any enforcement rules
out of .planning/ and ensure live enforcement remains in the appropriate live
docs/checks.

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.",

@coderabbitai coderabbitai Bot May 14, 2026

Copy link
Copy Markdown

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."
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