Merge pull request #2 from ayhammouda/codex/modernize-ai-dev-environment

modernize AI development environment

Author: ayhammouda

.cursorignore

@@ -0,0 +1 @@
+.planning/

.github/INTEGRATION-TEST.md

@@ -1,141 +1,126 @@
-# Integration Test Checklist
+# Manual MCP QA Runbook
 
-Manual verification steps for mcp-server-python-docs v0.1.0.
-These tests require human execution -- they cannot be automated.
+Use this document for manual MCP validation during development and before a
+release. The goal is to verify real client behavior after the automated test
+suite passes.
 
-## Prerequisites
-
-- [ ] All CI tests pass on main branch
-- [ ] `mcp-server-python-docs doctor` reports all checks PASS
-- [ ] Index is built: `mcp-server-python-docs build-index --versions 3.12,3.13`
-
-## Test 1: Claude Desktop Integration (SHIP-01)
-
-### Setup
+Release-specific sign-off still lives in [`.github/RELEASE.md`](RELEASE.md).
 
-1. Open Claude Desktop settings (Developer > Edit Config or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS)
-2. Add the following to `mcpServers`:
-   ```json
-   {
-     "mcpServers": {
-       "python-docs": {
-         "command": "uvx",
-         "args": ["mcp-server-python-docs"]
-       }
-     }
-   }
-   ```
-3. Restart Claude Desktop
-4. Verify the MCP server icon appears in the chat input area
-
-### Test Steps
-
-- [ ] **T1.1**: Ask Claude: "what is asyncio.TaskGroup"
-  - **Expected**: Response references `asyncio.TaskGroup` with a URI containing `library/asyncio-task.html`
-  - **Expected**: Response includes symbol information (not just generic LLM knowledge)
-  - **Actual result**: _______________
+## Prerequisites
 
-- [ ] **T1.2**: Ask Claude: "how do I use pathlib.Path.glob"
-  - **Expected**: Response references `pathlib` documentation with relevant section content
-  - **Actual result**: _______________
+- CI or local checks are green:
+  - `uv run ruff check src/ tests/`
+  - `uv run pyright src/`
+  - `uv run pytest --tb=short -q`
+- Local index build completed:
+  - `uv run mcp-server-python-docs build-index --versions 3.12,3.13`
+- Doctor passes:
+  - `uv run mcp-server-python-docs doctor`
+- If `uv` is not on `PATH`, use `python -m uv ...` instead
 
-- [ ] **T1.3**: Ask Claude: "search for json parsing in Python"
-  - **Expected**: Response includes hits from the `json` module documentation
-  - **Actual result**: _______________
+## Test 1: MCP Inspector quick loop
 
-- [ ] **T1.4**: Verify no errors in Claude Desktop developer console
-  - **Expected**: No MCP protocol errors or connection drops
-  - **Actual result**: _______________
+Use Inspector for fast local iteration before checking real clients.
 
-### Teardown
+### Start Inspector
 
-- Remove the `python-docs` entry from `mcpServers` (or keep for ongoing use)
+```bash
+npx @modelcontextprotocol/inspector uv --directory . run mcp-server-python-docs
+```
 
-## Test 2: Cursor Integration (SHIP-02)
+### Verify
+
+- [ ] Connect successfully over stdio
+- [ ] Confirm the tool list includes:
+  - `search_docs`
+  - `get_docs`
+  - `list_versions`
+  - `detect_python_version`
+- [ ] Call `search_docs` with query `asyncio.TaskGroup`, `kind="symbol"`, `version="3.13"`
+  - Expected: exact symbol hit with `library/asyncio-task.html`
+- [ ] Call `get_docs` for the returned slug and anchor
+  - Expected: section-level documentation, not an unrelated page dump
+- [ ] Call `list_versions`
+  - Expected: indexed versions appear with the configured default version
+- [ ] Call `detect_python_version`
+  - Expected: returns local interpreter information without breaking the session
+- [ ] Observe no protocol corruption or unexplained disconnects in Inspector
+
+## Test 2: Claude Desktop integration
 
 ### Setup
 
-1. Open Cursor Settings > MCP
-2. Add a new MCP server:
-   - **Name**: python-docs
-   - **Command**: `uvx`
-   - **Args**: `mcp-server-python-docs`
-3. Verify the server shows as connected (green indicator)
-
-### Test Steps
-
-- [ ] **T2.1**: In a chat or Composer session, ask: "what is asyncio.TaskGroup"
-  - **Expected**: Response references `asyncio.TaskGroup` with documentation content
-  - **Expected**: The MCP tool call is visible in the chat
-  - **Actual result**: _______________
-
-- [ ] **T2.2**: Ask: "show me the docs for collections.OrderedDict"
-  - **Expected**: Response includes `collections.OrderedDict` documentation
-  - **Actual result**: _______________
+1. Open Claude Desktop settings
+2. Add this server config:
+
+```json
+{
+  "mcpServers": {
+    "python-docs": {
+      "command": "uvx",
+      "args": ["mcp-server-python-docs"]
+    }
+  }
+}
+```
 
-- [ ] **T2.3**: Verify the server stays connected across multiple queries
-  - **Expected**: No disconnections or "server not responding" errors
-  - **Actual result**: _______________
+3. Fully restart Claude Desktop
+4. Verify the MCP server appears in the chat UI
 
-### Teardown
+### Checks
 
-- Remove or disable the python-docs MCP server in Cursor settings (or keep)
+- [ ] Ask: `what is asyncio.TaskGroup`
+  - Expected: response uses stdlib documentation, not only model prior knowledge
+- [ ] Ask: `how do I use pathlib.Path.glob`
+  - Expected: response cites the right docs section
+- [ ] Ask: `search for json parsing in Python`
+  - Expected: response surfaces `json` docs results
+- [ ] Check the Claude developer console
+  - Expected: no protocol errors or repeated reconnect loops
 
-## Test 3: Fresh Install Verification (SHIP-06 partial)
+## Test 3: Cursor integration
 
 ### Setup
 
-1. Create a throwaway virtualenv or use a machine without the package:
-   ```bash
-   # Option A: Fresh venv
-   uv venv /tmp/test-install && source /tmp/test-install/bin/activate
-
-   # Option B: Use uvx (isolated by default)
-   # No setup needed -- uvx creates its own isolated env
-   ```
+1. Open Cursor MCP settings
+2. Add a server:
+   - Name: `python-docs`
+   - Command: `uvx`
+   - Args: `mcp-server-python-docs`
+3. Confirm the server shows as connected
 
-### Test Steps
+### Checks
 
-- [ ] **T3.1**: Install from PyPI (after package is published):
-  ```bash
-  uvx mcp-server-python-docs --version
-  ```
-  - **Expected**: Prints `0.1.0`
-  - **Actual result**: _______________
+- [ ] Ask: `what is asyncio.TaskGroup`
+  - Expected: MCP tool usage is visible and the answer references the right docs
+- [ ] Ask: `show me the docs for collections.OrderedDict`
+  - Expected: response includes the relevant documentation section
+- [ ] Ask a second or third follow-up query
+  - Expected: the server stays connected across multiple calls
 
-- [ ] **T3.2**: Build the index:
-  ```bash
-  uvx mcp-server-python-docs build-index --versions 3.12,3.13
-  ```
-  - **Expected**: Downloads objects.inv files, builds index, prints success message
-  - **Actual result**: _______________
+## Test 4: Fresh install verification
 
-- [ ] **T3.3**: Run doctor:
-  ```bash
-  uvx mcp-server-python-docs doctor
-  ```
-  - **Expected**: All checks PASS
-  - **Actual result**: _______________
+Use this when validating the published package or a clean local environment.
 
-- [ ] **T3.4**: Verify the full README install flow works end-to-end
-  - **Expected**: Following README instructions from scratch produces a working server
-  - **Actual result**: _______________
-
-### Teardown
-
-```bash
-# Clean up throwaway venv if used
-rm -rf /tmp/test-install
-```
+On Windows, close the MCP client before rebuilding if the live index file is
+locked.
 
-## Sign-Off
+### Checks
 
-| Test | Pass/Fail | Tester | Date |
-|------|-----------|--------|------|
-| T1: Claude Desktop | | | |
-| T2: Cursor | | | |
-| T3: Fresh Install | | | |
+- [ ] `uvx mcp-server-python-docs --version`
+  - Expected: prints the current package version
+- [ ] `uvx mcp-server-python-docs build-index --versions 3.12,3.13`
+  - Expected: index build completes successfully
+- [ ] `uvx mcp-server-python-docs doctor`
+  - Expected: all required checks pass
+- [ ] Follow the README from scratch
+  - Expected: a new user can get to a working client configuration without using `.planning/`
 
-**Release approved**: [ ] Yes / [ ] No -- needs fixes
+## Evidence log
 
-**Notes**:
+| Test | Pass/Fail | Tester | Date | Notes |
+|------|-----------|--------|------|-------|
+| Inspector quick loop | | | | |
+| Claude Desktop | | | | |
+| Cursor | | | | |
+| Fresh install | | | | |

.gitignore

@@ -195,11 +195,9 @@ cython_debug/
 .pypirc
 
 # Cursor
-#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
-#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
-#  refer to https://docs.cursor.com/context/ignore-files
-.cursorignore
-.cursorindexingignore
+#  Keep repo-local Cursor context files tracked when present so the repository
+#  can define its own indexing boundaries.
+#  https://docs.cursor.com/context/ignore-files
 
 # Marimo
 marimo/_static/

.planning/FULL-CODEBASE-REVIEW.md

@@ -37,6 +37,10 @@ findings:
 status: issues_found
 ---
 
+> Archival note: this review is a historical snapshot from the generated GSD
+> workflow. It may describe issues that have already been fixed and should not
+> be treated as current repo truth.
+
 # Full Codebase: Code Review Report
 
 **Reviewed:** 2026-04-16T12:00:00Z

.planning/STATE.md

@@ -14,6 +14,10 @@ progress:
   percent: 53
 ---
 
+> Archival note: this file is historical GSD state, not current repository
+> truth. For active setup and workflow guidance, start with `README.md`,
+> `CONTRIBUTING.md`, and `AGENTS.md`.
+
 # Project State
 
 ## Project Reference

AGENTS.md

@@ -0,0 +1,97 @@
+# Repository Guidance
+
+## Project
+
+`mcp-server-python-docs` is a read-only MCP server for the official Python
+standard library documentation. It is built for end users who want precise,
+version-aware stdlib answers inside MCP clients such as Claude, Cursor, and
+Codex without relying on an external hosted docs API at query time.
+
+The repo's public credibility matters. Prefer changes that make the project
+easier to trust, easier to verify, and easier to contribute to over changes
+that merely add more AI or MCP setup.
+
+## Canonical Commands
+
+If `uv` is not installed yet:
+
+```bash
+python -m pip install uv
+```
+
+Bootstrap the repo:
+
+```bash
+uv sync --dev
+```
+
+If `uv` is not on your `PATH` after installation, reopen the shell or use
+`python -m uv ...` as a fallback.
+
+Core verification commands:
+
+```bash
+uv run ruff check src/ tests/
+uv run pyright src/
+uv run pytest --tb=short -q
+```
+
+Build and inspect a local docs index:
+
+```bash
+uv run mcp-server-python-docs build-index --versions 3.12,3.13
+uv run mcp-server-python-docs doctor
+uv run mcp-server-python-docs validate-corpus
+```
+
+Package smoke check:
+
+```bash
+uv build
+```
+
+## MCP Testing Flow
+
+Use this order when validating MCP behavior:
+
+1. Run the automated checks above.
+2. Use MCP Inspector for quick local iteration.
+3. Confirm real-client behavior with the runbook in `.github/INTEGRATION-TEST.md`.
+
+Client-facing integration and release runbooks live here:
+
+- `.github/INTEGRATION-TEST.md`
+- `.github/RELEASE.md`
+
+## Done Means
+
+Before calling work complete:
+
+- relevant lint, typecheck, and test commands have been run fresh
+- user-facing docs reflect the current behavior
+- MCP-related changes still work in the documented validation flow
+- no runtime API/tool surface changes were made unless explicitly requested
+
+## AI and MCP Policy
+
+- Use official documentation first for MCP, OpenAI/Codex, and Python SDK questions.
+- Avoid MCP sprawl. Do not add new MCP servers unless they clearly improve this
+  project's development or user experience.
+- Do not add repo-local custom skills by default. Add one only if a repeated
+  workflow is genuinely painful and no strong public pattern already covers it.
+- Follow existing test and documentation patterns before inventing new structure.
+
+## Context Hygiene
+
+Treat `.planning/` as archival project history, not live repo truth.
+
+Start with these files instead:
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `.github/INTEGRATION-TEST.md`
+- `tests/`
+
+The generated planning files may still be useful for maintainers who want the
+old GSD workflow context, but they should not drive routine implementation
+decisions.