fix(mcp): eliminate connection timeout and JSON-RPC notification compliance

Fix three bugs preventing MCP server from completing the initialize
handshake within the client's timeout window:

1. CRITICAL (serve.rs): move run_connect_time_catchup to a
   spawn_blocking background task so the MCP message loop enters
   immediately. The previous synchronous block_on call prevented
   the server from reading stdin until catch-up indexing finished,
   causing the client's initialize request to time out.

2. HIGH (schema.rs): make JsonRpcRequest.id optional with
   #[serde(default)]. JSON-RPC 2.0 notifications omit the id
   field entirely, so deserialization failed for compliant clients
   sending notifications/initialized.

3. MEDIUM (mod.rs): dispatch now returns Option<Value> — None for
   notifications (id=null) per JSON-RPC 2.0 §4.1. The message loop
   skips writing a response when dispatch returns None.

Author: alejandro-technology

AGENTS.md

@@ -0,0 +1,91 @@
+# AGENTS.md
+
+## Build & Run
+
+```bash
+cargo build
+cargo run -- <args>
+cargo run -- serve --mcp        # start MCP server
+cargo run -- init               # initialize a project
+cargo run -- index              # index codebase
+cargo run -- search "query"     # semantic search
+```
+
+## Testing
+
+```bash
+cargo test --all-targets        # run all tests
+cargo test --lib                # unit tests only
+cargo test --test '*'           # integration tests only
+cargo test <test_name>          # single test
+```
+
+## Lint & Format
+
+```bash
+cargo fmt                       # auto-format
+cargo fmt --check               # check formatting (CI)
+cargo clippy --all-targets -- -D warnings   # lint (CI)
+```
+
+All three (test, clippy, fmt --check) MUST pass before committing. CI enforces this.
+
+## Architecture
+
+```
+src/
+├── main.rs          # entry point — clap dispatch
+├── lib.rs           # module root + re-exports
+├── error.rs         # VectorCodeError (thiserror)
+├── types.rs         # Chunk, SearchResult, IndexMeta
+├── cli/             # one file per subcommand (init, index, search, serve, status, install, uninstall, upgrade)
+├── config/          # TOML config schema + loader (.vectorcode/config.toml)
+├── embedder/        # Embedder trait + providers (ONNX, Gemini, Ollama, OpenAI)
+├── engine/          # core orchestration: chunker (tree-sitter) → embedder → store
+├── mcp/             # MCP server: JSON-RPC 2.0 over stdio, tool handlers
+├── store/           # SQLite + sqlite-vec: db, chunks, files, meta tables
+└── watcher/         # file watcher (notify crate, debounced, gitignore-aware)
+```
+
+## Key Conventions
+
+- **Rust edition**: 2021, MSRV 1.75
+- **Error handling**: `VectorCodeError` (thiserror) for library code, `anyhow::Result` in `main.rs` and CLI handlers
+- **Async**: tokio runtime, `async-trait` for trait objects
+- **CLI**: clap with derive macros — one module per subcommand under `src/cli/`
+- **MCP protocol**: JSON-RPC 2.0 over stdio — schema types in `src/mcp/schema.rs`, handler dispatch in `src/mcp/server.rs`
+- **Embedding providers**: implement the `Embedder` trait from `src/embedder/mod.rs`
+- **Database**: rusqlite with bundled sqlite + sqlite-vec extension
+- **Tree-sitter**: one grammar per language, used by the chunker in `src/engine/`
+- **Tests**: unit tests inline (`#[cfg(test)] mod tests`), integration tests in `tests/`
+- **No unwrap/expect** in library code — propagate errors with `?`
+
+## Adding a New Embedding Provider
+
+1. Create `src/embedder/<provider>.rs`
+2. Implement the `Embedder` trait (async `embed` + `embed_batch`)
+3. Register in the provider factory in `src/embedder/mod.rs`
+4. Add config schema to `src/config/schema.rs`
+5. Add tests
+
+## Adding a New Tree-sitter Language
+
+1. Add the grammar crate to `Cargo.toml`
+2. Register in the chunker's language dispatch in `src/engine/`
+3. Add the extension mapping to `src/types.rs`
+
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `GEMINI_API_KEY` | Gemini embedding API key |
+| `OPENAI_API_KEY` | OpenAI embedding API key |
+| `VECTORCODE_PROVIDER` | Override provider |
+| `VECTORCODE_NO_WATCH` | Set `1` to disable file watcher |
+| `RUST_LOG` | tracing filter (e.g. `debug`, `vectorcode=trace`) |
+
+## Project Data
+
+- Config: `.vectorcode/config.toml`
+- Index DB: `.vectorcode/index.db`
+- Both are gitignored — never commit them

src/cli/install.rs

@@ -437,8 +437,7 @@ mod tests {
         let dir = tempfile::tempdir().unwrap();
         let config_path = dir.path().join("opencode.json");
 
-        let result =
-            install_for_agent(&AgentTarget::Opencode, &config_path, dir.path()).unwrap();
+        let result = install_for_agent(&AgentTarget::Opencode, &config_path, dir.path()).unwrap();
         assert!(result, "Should return true when config is created");
 
         assert!(config_path.exists(), "Config file should be created");
@@ -470,13 +469,11 @@ mod tests {
         let config_path = dir.path().join("config.json");
 
         // First install
-        let result1 =
-            install_for_agent(&AgentTarget::Cursor, &config_path, dir.path()).unwrap();
+        let result1 = install_for_agent(&AgentTarget::Cursor, &config_path, dir.path()).unwrap();
         assert!(result1, "First install should modify config");
 
         // Second install — should detect already configured
-        let result2 =
-            install_for_agent(&AgentTarget::Cursor, &config_path, dir.path()).unwrap();
+        let result2 = install_for_agent(&AgentTarget::Cursor, &config_path, dir.path()).unwrap();
         assert!(!result2, "Second install should be idempotent (no changes)");
     }
 
@@ -526,7 +523,10 @@ mod tests {
         assert!(entry["command"].is_string(), "Should have command field");
         assert!(entry["args"].is_array(), "Should have args array");
         let args = entry["args"].as_array().unwrap();
-        assert!(args.len() >= 4, "Should have serve, --mcp, --project-path, and path");
+        assert!(
+            args.len() >= 4,
+            "Should have serve, --mcp, --project-path, and path"
+        );
         assert!(entry["env"].is_object(), "Should have env object");
     }
 
@@ -578,7 +578,7 @@ mod tests {
         // Guard: if !force && skill_path.exists() { skip write }
         // force=false, exists=true → should NOT write
         let _force = false; // guard condition: only write if force || !exists
-        // Verify existing content preserved
+                            // Verify existing content preserved
         let content = std::fs::read_to_string(&skill_path).unwrap();
         assert_eq!(
             content, "existing content",

src/cli/mod.rs

@@ -95,7 +95,7 @@ pub fn resolve_project_path(cli_path: Option<&PathBuf>) -> PathBuf {
     }
 
     let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
-    
+
     // Walk up the tree looking for .vectorcode
     let mut current = cwd.as_path();
     loop {
@@ -107,7 +107,7 @@ pub fn resolve_project_path(cli_path: Option<&PathBuf>) -> PathBuf {
             None => break, // Reached root without finding it
         }
     }
-    
+
     // Fallback to cwd if not found anywhere (commands will handle the "not initialized" error)
     cwd
 }
@@ -282,33 +282,33 @@ mod tests {
         let temp_path = std::fs::canonicalize(temp.path()).unwrap();
         let prev_cwd = std::env::current_dir().unwrap();
         std::env::set_current_dir(&temp_path).unwrap();
-        
+
         let resolved = resolve_project_path(None);
         assert_eq!(resolved, temp_path);
-        
+
         std::env::set_current_dir(prev_cwd).unwrap();
     }
 
     #[test]
     fn resolve_project_path_finds_parent_dir() {
         let temp = tempfile::tempdir().unwrap();
         let project_root = std::fs::canonicalize(temp.path()).unwrap();
-        
+
         // Create .vectorcode in root
         std::fs::create_dir(project_root.join(".vectorcode")).unwrap();
-        
+
         // Create a deep subdirectory
         let deep_dir = project_root.join("src").join("cli").join("nested");
         std::fs::create_dir_all(&deep_dir).unwrap();
-        
+
         // Change cwd to deep directory
         let prev_cwd = std::env::current_dir().unwrap();
         std::env::set_current_dir(&deep_dir).unwrap();
-        
+
         // Resolve without explicit path should find the root
         let resolved = resolve_project_path(None);
         assert_eq!(resolved, project_root);
-        
+
         // Restore cwd
         std::env::set_current_dir(prev_cwd).unwrap();
     }
@@ -348,9 +348,8 @@ mod tests {
         // Deterministic: uses an empty temp dir — model not cached, so
         // ModelManager returns an error before reaching ONNX Runtime init.
         let empty_dir = tempfile::tempdir().unwrap();
-        let result = crate::embedder::onnx::OnnxEmbedder::from_model_dir(
-            empty_dir.path().to_path_buf(),
-        );
+        let result =
+            crate::embedder::onnx::OnnxEmbedder::from_model_dir(empty_dir.path().to_path_buf());
         assert!(result.is_err());
         let err_msg = format!("{}", result.err().unwrap());
         assert!(
@@ -365,9 +364,8 @@ mod tests {
         // Deterministic: empty model dir → error, verify it's the right
         // error variant (EmbedderError, not a panic or unexpected type).
         let empty_dir = tempfile::tempdir().unwrap();
-        let result = crate::embedder::onnx::OnnxEmbedder::from_model_dir(
-            empty_dir.path().to_path_buf(),
-        );
+        let result =
+            crate::embedder::onnx::OnnxEmbedder::from_model_dir(empty_dir.path().to_path_buf());
         assert!(result.is_err());
         let err_msg = format!("{}", result.err().unwrap());
         assert!(

src/cli/serve.rs

@@ -72,11 +72,6 @@ pub async fn execute(args: &ServeArgs, project_path: &std::path::Path) -> Result
     info!("  Watch:   {watch}");
     info!("  Debounce: {}ms", args.debounce);
 
-    // Connect-time catch-up (spec §14.3) — reconcile files before serving
-    if watch {
-        run_connect_time_catchup(&db, embedder.clone(), &cfg, project_path)?;
-    }
-
     // Create file watcher if enabled
     let watcher = if watch {
         let watcher_config = &cfg.watcher;
@@ -129,6 +124,28 @@ pub async fn execute(args: &ServeArgs, project_path: &std::path::Path) -> Result
 
     let mut server = McpServer::new(state);
 
+    // Spawn connect-time catch-up on a blocking thread (spec §14.3).
+    // Runs on the blocking pool so the MCP message loop enters immediately
+    // and the client's initialize request is answered without timeout.
+    // Uses spawn_blocking because Indexer (rusqlite internals) is !Send.
+    if watch {
+        let catchup_db_path = db_path.clone();
+        let catchup_embedder = embedder.clone();
+        let catchup_cfg = cfg.clone();
+        let catchup_project = project_path.to_path_buf();
+
+        tokio::task::spawn_blocking(move || {
+            if let Err(e) = run_connect_time_catchup(
+                &catchup_db_path,
+                catchup_embedder,
+                &catchup_cfg,
+                &catchup_project,
+            ) {
+                tracing::warn!("Connect-time catch-up failed: {e}");
+            }
+        });
+    }
+
     // Set up Ctrl+C handler
     let _ctrl_c = tokio::spawn(async {
         let _ = tokio::signal::ctrl_c().await;
@@ -146,14 +163,20 @@ pub async fn execute(args: &ServeArgs, project_path: &std::path::Path) -> Result
 ///
 /// Compares file mtimes on disk against the `files` table and runs incremental
 /// sync on any files that changed while no MCP server was running.
+///
+/// Called from `spawn_blocking` so the MCP message loop starts immediately
+/// and the client's `initialize` request is answered without timeout.
 fn run_connect_time_catchup(
-    db: &Database,
+    db_path: &std::path::Path,
     embedder: Arc<dyn crate::embedder::Embedder>,
     cfg: &config::schema::Config,
     project_path: &std::path::Path,
 ) -> Result<()> {
     info!("Running connect-time catch-up sync...");
 
+    // Open DB to list tracked files
+    let db = Database::open(db_path).map_err(|e| anyhow::anyhow!("{e}"))?;
+
     let tracked_files = files::list_all_files(db.conn())?;
     let mut changed_paths = Vec::new();
 
@@ -190,13 +213,12 @@ fn run_connect_time_catchup(
         changed_paths.len()
     );
 
-    // Open a new DB handle for the indexer (the original is borrowed)
-    let db_path = project_path.join(".vectorcode").join("index.db");
-    let sync_db = Database::open(&db_path).map_err(|e| anyhow::anyhow!("{e}"))?;
-
+    // Open a fresh DB handle for the indexer (SQLite handles concurrent access)
+    let sync_db = Database::open(db_path).map_err(|e| anyhow::anyhow!("{e}"))?;
     let indexer = Indexer::new(sync_db, embedder, cfg.indexing.clone());
 
-    // Use a blocking runtime context for the sync
+    // block_on is safe here because we are on a spawn_blocking thread,
+    // not the main async runtime.
     let rt = tokio::runtime::Handle::current();
     let report = rt.block_on(indexer.index_files(&changed_paths, project_path))?;
 
@@ -376,7 +398,10 @@ mod tests {
             debounce: 2000,
         };
         let result = rt.block_on(execute(&serve_args, project_path));
-        assert!(result.is_err(), "Should fail with Gemini provider missing key");
+        assert!(
+            result.is_err(),
+            "Should fail with Gemini provider missing key"
+        );
         let err = result.unwrap_err().to_string();
         assert!(
             err.contains("API key") || err.contains("GEMINI_API_KEY"),

src/cli/uninstall.rs

@@ -238,8 +238,12 @@ mod tests {
         let config_path = dir.path().join("config.json");
 
         // Install
-        let installed =
-            crate::cli::install::install_for_agent(&AgentTarget::Opencode, &config_path, dir.path()).unwrap();
+        let installed = crate::cli::install::install_for_agent(
+            &AgentTarget::Opencode,
+            &config_path,
+            dir.path(),
+        )
+        .unwrap();
         assert!(installed);
 
         // Verify entry exists

src/embedder/model_manager.rs

@@ -25,7 +25,10 @@ const MODEL_FILENAME: &str = "model.onnx";
 /// HuggingFace path for the quantized ONNX model, selected by platform.
 /// Falls back to the unquantized `onnx/model.onnx` (~90MB) if no quantized variant matches.
 const ONNX_MODEL_PATH: &str = {
-    if cfg!(all(target_arch = "aarch64", any(target_os = "macos", target_os = "linux"))) {
+    if cfg!(all(
+        target_arch = "aarch64",
+        any(target_os = "macos", target_os = "linux")
+    )) {
         "onnx/model_qint8_arm64.onnx" // ~23MB, optimized for ARM64
     } else if cfg!(all(
         target_arch = "x86_64",