Merge branch 'mcp-upgrade-notes'

Author: johnhuang316

.well-known/mcp.json

@@ -0,0 +1,28 @@
+{
+    "$schema": "https://modelcontextprotocol.io/schemas/mcp.json",
+    "mcpServers": {
+        "code-index": {
+            "command": "uv",
+            "args": [
+                "run",
+                "code-index-mcp"
+            ],
+            "transport": {
+                "type": "stdio"
+            },
+            "metadata": {
+                "name": "Code Index MCP",
+                "description": "Local code-aware MCP server with project indexing, search, and file tools.",
+                "homepage": "https://github.com/johnhuang316/code-index-mcp",
+                "capabilities": [
+                    "code-search",
+                    "symbol-indexing",
+                    "file-system"
+                ]
+            }
+        }
+    },
+    "llmfeed_extension": {
+        "path": ".well-known/mcp.llmfeed.json"
+    }
+}

.well-known/mcp.llmfeed.json

@@ -0,0 +1,32 @@
+{
+    "$schema": "https://modelcontextprotocol.io/schemas/mcp-llmfeed.json",
+    "feed_type": "mcp_server_list",
+    "servers": [
+        {
+            "id": "code-index",
+            "name": "Code Index MCP",
+            "description": "Exposes project-aware indexing, search, and file utilities for LLM agents via MCP transports.",
+            "version": "2.8.1",
+            "transport": "stdio",
+            "command": "uv",
+            "args": [
+                "run",
+                "code-index-mcp"
+            ],
+            "links": {
+                "documentation": "https://github.com/johnhuang316/code-index-mcp#readme",
+                "source": "https://github.com/johnhuang316/code-index-mcp"
+            },
+            "capabilities": [
+                "code-search",
+                "symbol-indexing",
+                "file-system"
+            ],
+            "tags": [
+                "fastmcp",
+                "code-intelligence",
+                "watcher"
+            ]
+        }
+    ]
+}

README.md

@@ -87,6 +87,21 @@ Linux and macOS already expose the required XDG paths and `HOME`, so you can usu
 table there.
 Add overrides only if you run the CLI inside a restricted container.
 
+### FastMCP & Discovery Manifests
+
+- Run `fastmcp run fastmcp.json` to launch the server via [FastMCP](https://fastmcp.wiki/) with
+  the correct source entrypoint and dependency metadata. Pass `--project-path` (or call the
+  `set_project_path` tool after startup) so the index boots against the right repository.
+- Serve or copy `.well-known/mcp.json` to share a standards-compliant MCP manifest. Clients that
+  support the `.well-known` convention (e.g., Claude Desktop, Codex CLI) can import this file
+  directly instead of crafting configs manually.
+- Publish `.well-known/mcp.llmfeed.json` when you want to expose the richer LLM Feed metadata.
+  It references the same `code-index` server definition plus documentation/source links, which
+  helps registries present descriptions, tags, and capabilities automatically.
+
+When sharing the manifests, remind consumers to supply `--project-path` (or to call
+`set_project_path`) so the server indexes the intended repository.
+
 ## Typical Use Cases
 
 **Code Review**: "Find all places using the old API"  

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.

fastmcp.json

@@ -0,0 +1,43 @@
+{
+    "$schema": "https://fastmcp.wiki/en/schemas/fastmcp.json",
+    "name": "Code Index MCP",
+    "description": "Indexes a local repository and exposes search, indexing, and file utilities via the Model Context Protocol.",
+    "license": "MIT",
+    "keywords": [
+        "mcp",
+        "code-index",
+        "search",
+        "fastmcp"
+    ],
+    "links": [
+        {
+            "rel": "source",
+            "href": "https://github.com/johnhuang316/code-index-mcp"
+        },
+        {
+            "rel": "documentation",
+            "href": "https://github.com/johnhuang316/code-index-mcp#readme"
+        }
+    ],
+    "source": {
+        "path": "src/code_index_mcp/server.py",
+        "entrypoint": "mcp"
+    },
+    "environment": {
+        "python": ">=3.10",
+        "dependencies": [
+            "mcp>=1.21.0,<2.0.0",
+            "watchdog>=3.0.0",
+            "tree-sitter>=0.20.0",
+            "tree-sitter-javascript>=0.20.0",
+            "tree-sitter-typescript>=0.20.0",
+            "tree-sitter-java>=0.20.0",
+            "tree-sitter-zig>=0.20.0",
+            "pathspec>=0.12.1",
+            "msgpack>=1.0.0"
+        ]
+    },
+    "deployment": {
+        "transport": "stdio"
+    }
+}

pyproject.toml

@@ -13,7 +13,7 @@ authors = [
     {name = "johnhuang316"}
 ]
 dependencies = [
-    "mcp>=0.3.0",
+    "mcp>=1.21.0,<2.0.0",
     "watchdog>=3.0.0",
     "tree-sitter>=0.20.0",
     "tree-sitter-javascript>=0.20.0",

requirements.txt

@@ -1,4 +1,4 @@
-mcp>=0.3.0
+mcp>=1.21.0,<2.0.0
 watchdog>=3.0.0
 protobuf>=4.21.0
 tree-sitter>=0.20.0

src/code_index_mcp/server.py

@@ -31,9 +31,7 @@
 from .services.index_management_service import IndexManagementService
 from .services.code_intelligence_service import CodeIntelligenceService
 from .services.system_management_service import SystemManagementService
-from .utils import (
-    handle_mcp_resource_errors, handle_mcp_tool_errors
-)
+from .utils import handle_mcp_tool_errors
 
 # Setup logging without writing to files
 def setup_indexing_performance_logging():
@@ -126,27 +124,6 @@ async def indexer_lifespan(_server: FastMCP) -> AsyncIterator[CodeIndexerContext
 # Create the MCP server with lifespan manager
 mcp = FastMCP("CodeIndexer", lifespan=indexer_lifespan, dependencies=["pathlib"])
 
-# ----- RESOURCES -----
-
-@mcp.resource("config://code-indexer")
-@handle_mcp_resource_errors
-def get_config() -> str:
-    """Get the current configuration of the Code Indexer."""
-    ctx = mcp.get_context()
-    return ProjectManagementService(ctx).get_project_config()
-
-@mcp.resource("files://{file_path}")
-@handle_mcp_resource_errors
-def get_file_content(file_path: str) -> str:
-    """Get the content of a specific file."""
-    ctx = mcp.get_context()
-    # Use FileService for simple file reading - this is appropriate for a resource
-    return FileService(ctx).get_file_content(file_path)
-
-# Removed: structure://project resource - not necessary for most workflows
-# Removed: settings://stats resource - this information is available via get_settings_info() tool
-# and is more of a debugging/technical detail rather than context AI needs
-
 # ----- TOOLS -----
 
 @mcp.tool()

src/code_index_mcp/utils/error_handler.py

@@ -76,8 +76,7 @@ def handle_mcp_resource_errors(func: Callable) -> Callable:
     Example:
         @mcp.resource("config://code-indexer")
         @handle_mcp_resource_errors
-        def get_config() -> str:
-            ctx = mcp.get_context()
+        def get_config(ctx: Context) -> str:
             from ..services.project_management_service import ProjectManagementService
             return ProjectManagementService(ctx).get_project_config()
     """