docs: add mcp restart playbook

Author: johnhuang316

docs/mcp-restart-playbook.md

@@ -0,0 +1,83 @@
+# MCP Restart Playbook (November 10, 2025)
+
+This runbook is for the first LLM/agent session *after* the MCP server restarts (for example, after bumping dependencies or recycling the FastMCP process). Follow every step in order so we quickly regain context, validate the upgraded toolchain, and communicate status to the rest of the team.
+
+---
+
+## 1. Current Snapshot
+- **Branch**: `mcp-upgrade-notes`
+- **Python**: 3.13.2 (uv-managed)
+- **Key dependency**: `mcp>=1.21.0,<2.0.0` (synced across `pyproject.toml`, `requirements.txt`, and `uv.lock`)
+- **Latest validation**: `uv run pytest` — 16 tests passed on **November 10, 2025 @ 02:05 UTC**
+- **Reference doc**: `docs/mcp-upgrade-notes.md` (rationale, API deltas, validation checklist)
+
+If any of these details drift (new branch, newer SDK, etc.) update this file before handing off.
+
+---
+
+## 2. Post-Restart MCP Calls (must run all tools)
+Run through every exposed MCP primitive to guarantee parity after restart. Use the table below as a checklist and record each response summary.
+
+| # | Tool | Minimum Input | Expected outcome |
+|---|------|---------------|------------------|
+| 1 | `set_project_path` | `path="C:\Users\p10362321\project\code-index-mcp"` | Indexed ~149 files; watcher initialized. |
+| 2 | `build_deep_index` | - | Project re-indexed. Found ~149 files / ~1,070 symbols. |
+| 3 | `search_code_advanced` | `pattern="FastMCP", file_pattern="src/**/*.py", max_results=20` | Hits in `server.py` plus pagination metadata. |
+| 4 | `find_files` | `pattern="tests/**/*.py"` | Returns 10 test modules. |
+| 5 | `get_file_summary` | `file_path="src/code_index_mcp/server.py"` | ~390 lines, 20+ functions reported. |
+| 6 | `refresh_index` | - | Shallow index re-built with ~149 files. |
+| 7 | `get_settings_info` | - | Shows temp/settings dirs, writable=true. |
+| 8 | `create_temp_directory` | - | Confirms directory exists/created. |
+| 9 | `check_temp_directory` | - | Lists `index.db`, `index.msgpack`, `index.shallow.json`. |
+|10 | `clear_settings` | - | Project settings, index, and cache have been cleared (rerun #1 + #2). |
+|11 | `refresh_search_tools` | - | Available: ['ripgrep', 'basic']; preferred: ripgrep. |
+|12 | `get_file_watcher_status` | - | status: active, debounce_seconds=6. |
+|13 | `configure_file_watcher` | `enabled=True, debounce_seconds=6` | Confirmation message (restart may be required). |
+
+Notes:
+- After running `clear_settings`, immediately repeat `set_project_path` + `build_deep_index` to restore context before proceeding.
+- If any tool fails, stop the playbook, capture output, and escalate before continuing.
+
+Log each response summary in the session notes so the next engineer knows everything is green.
+
+---
+
+## 3. CLI / End-to-End Smoke
+Run these in the repo root once the MCP tools succeed:
+
+```powershell
+uv run code-index-mcp --project-path C:\Users\p10362321\project\code-index-mcp
+uv run pytest
+```
+
+- Treat any warning or stderr output as a blocker.
+- Capture timestamps + durations; attach to release prep if we are close to tagging.
+
+---
+
+## 4. Communicate Status
+When handing the session back to the team, summarize:
+
+- **SDK state**: Confirm we are still on MCP 1.21.0 (with context injection + capability helpers).
+- **Tool cache**: Mention that clients should re-cache tool lists after restart (FastMCP now enforces metadata changes).
+- **Known issues**: Note any skipped steps, flaky tests, or manual interventions.
+- **Next action**: “Ready for release prep” or “Need follow-up on X” — whichever applies after the smoke tests.
+
+---
+
+## 5. Troubleshooting Quick Reference
+- **`set_project_path` fails** → Ensure the repo path is accessible (sandbox permissions) and no other agent locked `index.db`. Run `clear_settings()` then retry.
+- **Search returns zero results** → Run `refresh_search_tools()`; if ripgrep missing, fall back to `basic` and flag the infra team.
+- **Watcher inactive** → Call `configure_file_watcher(enabled=True)` and `refresh_index()`. Document if it remains inactive.
+- **CLI smoke exits non-zero** → Capture full stdout/stderr, file an issue linked to `docs/mcp-upgrade-notes.md`, and pause release work.
+
+Keep this section updated with any new gotchas discovered during restarts.
+
+---
+
+## 6. Hand-off Checklist
+- [ ] Steps 1–4 executed and logged in the current session.
+- [ ] Any deviations documented (include timestamps + command output).
+- [ ] This playbook reviewed/updated if procedures changed.
+
+If all boxes are checked, the MCP server is considered healthy and ready for normal development or release activities.

docs/mcp-upgrade-notes.md

@@ -0,0 +1,28 @@
+# MCP Upgrade Notes (November 2025)
+
+## Why this upgrade matters
+- `mcp` 1.21.0 was published to PyPI on 2025-11-06, so we are at least 17 point releases behind the current SDK and missing recent transport, auth, and client-surface fixes.
+- The MCP governance group will cut the next specification release on 2025-11-25 (RC on 2025-11-11), so validating 1.21.0 now keeps us aligned ahead of another protocol bump.
+
+## Dependency & packaging considerations
+1. Run `uv lock --upgrade mcp` (or equivalent) so `uv.lock` stops pinning 1.4.1 and picks up the 1.21.0 wheels plus their refreshed transitive set (Starlette 0.49.1, AnyIO/HTTPX upgrades, etc.).
+2. Re-run `uv run pytest` and our smoke commands (`uv run code-index-mcp --project-path <repo>`) because AnyIO cancellation semantics and Starlette ASGI changes can surface subtle regressions in watcher services.
+3. Publish the lockfile and version bumps together; our release checklist requires pyproject + package __init__ + uv.lock to stay in sync.
+
+## API & runtime changes to verify
+- SEP-985 landed in 1.21.0, adding OAuth-protected resource metadata fallback: confirm our SettingsService handles `WWW-Authenticate` responses and that CLI flags surface any required bearer tokens.
+- `ClientSession.get_server_capabilities()` is new; if clients or integration tests introspect capabilities manually, migrate to this helper.
+- Starlette 0.49.1 ships tighter ASGI scope validation; double-check our SSE transport and progress notifications.
+
+## Recommended practices for 1.21.x
+1. **Depend on Context injection, not globals.** Annotate `ctx: Context` parameters so FastMCP injects the request context automatically instead of calling `mcp.get_context()` directly; this keeps us compatible with async-only handlers and future dependency-injection changes.
+2. **Cache expensive tool listings in clients.** Newer agents (OpenAI Agents SDK, Claude Desktop) call `list_tools()` on every run; set `cache_tools_list=True` only when our tool roster is static and call `invalidate_tools_cache()` after deployments.
+3. **Respect capability negotiation each session.** Protocol version 2025-06-18 remains current, and version negotiation happens during `initialize`; ensure our server exposes accurate `capabilities` metadata and gracefully errors when clients offer only future versions.
+4. **Stay ahead of November spec changes.** The upcoming 2025-11-25 spec focuses on additional security hardening. Schedule time to exercise the RC (available 2025-11-11) so we can absorb any required surface changes early.
+5. **Document OAuth and transport choices.** With SEP-985 and other auth SEPs in flight, record which flows (`device`, `jwt-bearer`, etc.) each deployment expects, and prefer the Streamable HTTP transport when exposing remote servers to benefit from the latest security guidance.
+
+## Validation checklist before merging
+- [ ] Lockfile regenerated (`uv lock --upgrade mcp`) and `uv run python -m code_index_mcp.server --help` still succeeds.
+- [ ] `uv run code-index-mcp --project-path <repo>` exercises `set_project_path`, `build_deep_index`, and `search_code_advanced` end-to-end.
+- [ ] Smoke Claude Desktop / Codex CLI against the upgraded server; confirm resources + tools enumerate and that tool caching behaves as expected.
+- [ ] Update release notes + AGENTS.md summary once 1.21.x is verified in staging.