bluera-knowledge 0.11.12 → 0.11.14

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.12",
+  "version": "0.11.14",
   "description": "Clone repos, crawl docs, search locally. Fast, authoritative answers for AI coding agents.",
   "mcpServers": {
     "bluera-knowledge": {

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.11.14](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.14) (2026-01-10)
+
+
+### Features
+
+* **scripts:** add post-release npm validation script ([e4c29a0](https://github.com/blueraai/bluera-knowledge/commit/e4c29a0c83907de4bc293a69a58412629457fb22))
+* **scripts:** add suggest, sync, serve, mcp tests to npm validation ([49d85da](https://github.com/blueraai/bluera-knowledge/commit/49d85dad1a89691060c12f152d644844baf6e6e6))
+* **scripts:** log expected vs installed version in validation script ([c77d039](https://github.com/blueraai/bluera-knowledge/commit/c77d039b27a3ccf54d50006af161ac4dcfea7b21))
+
+
+### Bug Fixes
+
+* **cli:** plugin-api commands now respect global options ([d3cca02](https://github.com/blueraai/bluera-knowledge/commit/d3cca02ffc679ffc187b76c7682f3cc177eabdea))
+* **plugin:** properly close services after command execution ([eeaf743](https://github.com/blueraai/bluera-knowledge/commit/eeaf743750be73fd9c7a9e72440b2fd0fb5a53fa))
+* **scripts:** show real-time output in validation script ([8a4bdec](https://github.com/blueraai/bluera-knowledge/commit/8a4bdec8b63c504d34ba35bfe19da795f7f7fd07))
+* **scripts:** use mktemp for temp directories in validation script ([3107861](https://github.com/blueraai/bluera-knowledge/commit/3107861bd7a966016fde2a121469dd84756f39be))
+* **search:** add defaults for env vars so CLI works standalone ([b2d2ce5](https://github.com/blueraai/bluera-knowledge/commit/b2d2ce534e8cd2ba0fc0abdac505c912a1a76035))
+
+## [0.11.13](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.13) (2026-01-10)
+
+
+### Features
+
+* **scripts:** add post-release npm validation script ([e4c29a0](https://github.com/blueraai/bluera-knowledge/commit/e4c29a0c83907de4bc293a69a58412629457fb22))
+* **scripts:** add suggest, sync, serve, mcp tests to npm validation ([49d85da](https://github.com/blueraai/bluera-knowledge/commit/49d85dad1a89691060c12f152d644844baf6e6e6))
+* **scripts:** log expected vs installed version in validation script ([c77d039](https://github.com/blueraai/bluera-knowledge/commit/c77d039b27a3ccf54d50006af161ac4dcfea7b21))
+
+
+### Bug Fixes
+
+* **cli:** plugin-api commands now respect global options ([d3cca02](https://github.com/blueraai/bluera-knowledge/commit/d3cca02ffc679ffc187b76c7682f3cc177eabdea))
+* **plugin:** properly close services after command execution ([eeaf743](https://github.com/blueraai/bluera-knowledge/commit/eeaf743750be73fd9c7a9e72440b2fd0fb5a53fa))
+* **scripts:** show real-time output in validation script ([8a4bdec](https://github.com/blueraai/bluera-knowledge/commit/8a4bdec8b63c504d34ba35bfe19da795f7f7fd07))
+* **scripts:** use mktemp for temp directories in validation script ([3107861](https://github.com/blueraai/bluera-knowledge/commit/3107861bd7a966016fde2a121469dd84756f39be))
+* **search:** add defaults for env vars so CLI works standalone ([b2d2ce5](https://github.com/blueraai/bluera-knowledge/commit/b2d2ce534e8cd2ba0fc0abdac505c912a1a76035))
+
 ## [0.11.12](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.12) (2026-01-10)
 
 

package/README.md

@@ -122,6 +122,47 @@ Bluera Knowledge enables option 3 by building a searchable knowledge base from *
 
 ---
 
+## 🎯 When Claude Code Should Query BK
+
+**The simple rule: Query BK for any question about libraries, dependencies, or reference material.**
+
+BK is cheap (~100ms, no rate limits), authoritative (actual source code), and complete (includes tests and internal APIs). Claude Code should query it frequently for external code questions.
+
+### Always Query BK For:
+
+| Question Type | Examples |
+|--------------|----------|
+| **Library internals** | "How does Express handle middleware errors?", "What does useEffect cleanup do?" |
+| **API signatures** | "What parameters does axios.create() accept?", "What options can I pass to Hono?" |
+| **Error handling** | "What errors can Zod throw?", "Why might this library return undefined?" |
+| **Version behavior** | "What changed in React 18?", "Is this method deprecated?" |
+| **Configuration** | "What config options exist for Vite?", "What are the defaults?" |
+| **Testing patterns** | "How do the library authors test this?", "How should I mock this?" |
+| **Performance/internals** | "Is this cached internally?", "What's the complexity?" |
+| **Security** | "How does this library validate input?", "Is this safe against injection?" |
+| **Integration** | "How do I integrate X with Y?", "What's the idiomatic way to use this?" |
+
+### DO NOT Query BK For:
+
+| Question Type | Use Instead |
+|--------------|-------------|
+| **Your project code** | Grep/Read directly ("Where is OUR auth middleware?") |
+| **General concepts** | Training data ("What is a closure?") |
+| **Breaking news** | Web search ("Latest React release notes") |
+
+### Quick Pattern Matching:
+
+```
+"How does [library] work..."           → Query BK
+"What does [library function] do..."   → Query BK
+"What options does [library] accept..."→ Query BK
+"What errors can [library] throw..."   → Query BK
+"Where is [thing] in OUR code..."      → Grep/Read directly
+"What is [general concept]..."         → Training data
+```
+
+---
+
 ## 💰 Token Efficiency
 
 Beyond speed and accuracy, Bluera Knowledge can **significantly reduce token consumption** for code-related queries—typically saving 60-75% compared to web search approaches.
@@ -196,12 +237,15 @@ Bluera Knowledge isn't always the most token-efficient choice:
 
 ### 💡 Best Practice
 
-Let Claude Code decide when to use Bluera Knowledge:
-- For **library-specific, version-specific, or implementation questions** → BK saves tokens and increases accuracy
-- For **general programming concepts** → Training data is more efficient
-- For **current events** → Web search is necessary
+**Default to BK for library questions.** It's cheap, fast, and authoritative:
+
+| Question Type | Action | Why |
+|--------------|--------|-----|
+| Library internals, APIs, errors, versions, config | **Query BK first** | Source code is definitive, 60-85% token savings |
+| General programming concepts | Skip BK | Training data is sufficient |
+| Breaking news, release notes | Web search | BK only has indexed content |
 
-The plugin's Skills teach Claude Code these patterns, so it automatically uses the most efficient approach for each question.
+The plugin's Skills teach Claude Code these patterns automatically. When in doubt about a dependency, query BK—it's faster and more accurate than guessing or web searching.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.12",
+  "version": "0.11.14",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {

package/skills/knowledge-search/SKILL.md

@@ -7,40 +7,85 @@ description: Teaches how to use Bluera Knowledge for accessing library sources a
 
 BK provides access to **definitive library sources** for your project dependencies.
 
-## Purpose: Authoritative References, Not Project Search
+## The Rule: Query BK for External Code
 
-**CKB is for**: Reference material and external sources
-- **Library sources**: Clone Vue.js/Pydantic/Hono for authoritative API reference
-- **Specifications**: Add project requirements, API specs, RFCs
-- **Documentation**: Add design docs, architecture guides, research papers
-- **Reference material**: Best practices, coding standards, examples
+**Any question about libraries, dependencies, or indexed reference material should query BK.**
 
-**CKB is NOT for**: Searching your current project code
-- Use Grep/Read directly on project files
-- BK stores are for external reference material
+BK is:
+- **Cheap**: ~100ms response, unlimited queries, no rate limits
+- **Authoritative**: Actual source code, not blog posts or training data
+- **Complete**: Includes tests, examples, internal APIs, configuration
+
+## Always Query BK For:
+
+**Library implementation:**
+- "How does Express handle middleware errors?"
+- "What does React's useEffect cleanup actually do?"
+- "How is Pydantic validation implemented?"
+
+**API signatures and options:**
+- "What parameters does axios.create() accept?"
+- "What options can I pass to hono.use()?"
+- "What's the signature of zod.object()?"
+
+**Error handling:**
+- "What errors can this library throw?"
+- "Why might this function return undefined?"
+- "What validation does Zod perform?"
+
+**Version-specific behavior:**
+- "What changed in React 18?"
+- "Is this deprecated in Express 5?"
+- "Does my version support this?"
+
+**Configuration:**
+- "What config options exist for Vite?"
+- "What are the default values?"
+- "What environment variables does this use?"
+
+**Testing:**
+- "How do the library authors test this?"
+- "How should I mock this in tests?"
+- "What edge cases do the tests cover?"
+
+**Performance:**
+- "Is this cached internally?"
+- "What's the complexity of this operation?"
+- "Does this run async or sync?"
+
+**Security:**
+- "How does this validate input?"
+- "Is this safe against injection?"
+- "How are credentials handled?"
+
+**Integration:**
+- "How do I integrate X with Y?"
+- "What's the idiomatic usage pattern?"
+- "How do examples in the library do this?"
 
 ## Two Ways to Access Library Sources
 
-### 1. Vector Search (MCP or slash command)
-Find concepts and patterns across library docs:
+### 1. Vector Search (Discovery)
+Find concepts and patterns across indexed content:
 ```
 search("vue reactivity system")
 /bluera-knowledge:search "pydantic custom validators"
 ```
 
-### 2. Direct File Access (Grep/Read)
+### 2. Direct File Access (Precision)
 Precise lookups in cloned library source:
 ```
 Grep: pattern="defineReactive" path=".bluera/bluera-knowledge/repos/vue/"
 Read: .bluera/bluera-knowledge/repos/pydantic/pydantic/validators.py
 ```
 
-## Both Are Valid!
+Both are valid! Use vector search for discovery, Grep/Read for specific functions.
 
-You can use **either or both** approaches on the same cloned repo:
-- Vector search to discover relevant files
-- Grep/Read to find specific functions/classes
-- Or just Grep/Read if you know what you're looking for
+## DO NOT Query BK For:
+
+- **Your project code** → Use Grep/Read directly
+- **General concepts** → Use training data ("What is a closure?")
+- **Breaking news** → Use web search ("Latest React release")
 
 ## Example Workflow
 
@@ -52,3 +97,14 @@ Claude:
 3. Read file: `.bluera/bluera-knowledge/repos/vue/packages/reactivity/src/computed.ts`
 4. Grep for implementation: pattern="class ComputedRefImpl"
 5. Explain with authoritative source code examples
+
+## Quick Reference
+
+```
+[library] question        → Query BK
+[your code] question      → Grep/Read directly
+[concept] question        → Training data
+[news/updates] question   → Web search
+```
+
+BK is cheap and fast. Query it liberally for library questions.

package/skills/when-to-query/SKILL.md

@@ -3,64 +3,158 @@ name: when-to-query
 description: Decision guide for when to query Bluera Knowledge stores vs using Grep/Read on current project. Query BK for library/dependency questions and reference material. Use Grep/Read for current project code, debugging, and implementation details. Includes setup instructions and mental model.
 ---
 
-# When to Query BK vs Current Project
+# When to Query Bluera Knowledge
 
-## Query BK When:
+## The Rule: BK First for External Code
 
-**Questions about libraries/dependencies:**
-- "How does Vue's reactivity system work?"
-- "What are Pydantic's built-in validators?"
-- "How should I use Pino's child loggers?"
-- "What middleware does Hono provide?"
+**When the question involves libraries, dependencies, or reference material, query BK first.**
 
-**Reference material questions:**
-- "What does the API spec say about authentication?"
-- "What are the project requirements for error handling?"
-- "How does the architecture doc describe the data flow?"
-- "What coding standards apply to this project?"
+BK provides authoritative source code from the actual libraries. This is:
+- **More accurate** than training data (which may be outdated)
+- **Faster** than web search (~100ms vs 2-5 seconds)
+- **More complete** than documentation sites (includes tests, examples, internal APIs)
+- **Zero rate limits** (local, unlimited queries)
 
-**Learning library APIs:**
-- Discovering available options/configs
-- Finding usage examples from library itself
-- Understanding internal implementation
+---
 
-**Verifying specifications:**
-- Checking exact requirements
-- Finding edge cases in specs
-- Understanding design decisions
+## ALWAYS Query BK For:
+
+### Library Implementation Questions
+- "How does Express handle middleware errors?"
+- "What does `useEffect` cleanup actually do internally?"
+- "How is Pydantic validation implemented?"
+- "What happens when lodash `debounce` is called?"
+- "How does React's reconciliation work?"
+
+### API and Method Questions
+- "What parameters does `axios.create()` accept?"
+- "What's the signature of `zod.object()`?"
+- "What options can I pass to `hono.use()`?"
+- "What events does EventEmitter emit?"
+- "What methods are available on `prisma.client`?"
+
+### Error and Exception Handling
+- "What errors can this library throw?"
+- "How do I catch validation errors in Zod?"
+- "What does this error code mean in library X?"
+- "Why might this function return undefined?"
+- "What validation does this library perform?"
+
+### Version-Specific Behavior
+- "What changed in React 18's concurrent mode?"
+- "How does this work in Express 4 vs 5?"
+- "Is this method deprecated in the latest version?"
+- "What's the migration path from v2 to v3?"
+- "Does my version support this feature?"
+
+### Configuration and Options
+- "What configuration options exist for Vite?"
+- "What are the default values for these options?"
+- "How do I customize the behavior of X?"
+- "What environment variables does this library use?"
+- "What's the full schema for this config?"
+
+### Testing Patterns
+- "How do the library authors test this feature?"
+- "How should I mock this library in tests?"
+- "What fixtures do I need for testing this integration?"
+- "What edge cases does the library's test suite cover?"
+
+### Performance and Internals
+- "Is this operation cached internally?"
+- "What's the time complexity of this method?"
+- "How is this optimized in the library?"
+- "Does this run synchronously or asynchronously?"
+- "What's the memory footprint of this?"
+
+### Security and Validation
+- "How does this library validate input?"
+- "What sanitization is applied?"
+- "How are credentials handled internally?"
+- "Is this safe against injection attacks?"
+
+### Integration and Patterns
+- "How do I integrate library X with library Y?"
+- "What's the idiomatic way to use this API?"
+- "How do examples in the library do this?"
+- "What patterns does this library use?"
+- "What's the recommended project structure?"
+
+### Reference Material
+- "What does the API spec say about X?"
+- "What are the project requirements for Y?"
+- "How does the architecture doc describe Z?"
+- "What coding standards apply here?"
 
-## Query Current Project (Grep/Read) When:
+---
 
-**Working on YOUR code:**
-- "Where is the authentication middleware?"
-- "Find all API endpoints"
-- "Show me the database models"
+## DO NOT Query BK For:
 
-**Debugging YOUR code:**
-- Reading error traces
-- Following call stacks
-- Checking variable usage
+### Current Project Code
+Use Grep/Read directly:
+- "Where is the authentication middleware in THIS project?"
+- "Show me OUR database models"
+- "Find all API endpoints WE defined"
 
-## Setup First: Add Important Dependencies
+### General Concepts
+Use training data (no tool needed):
+- "What is a closure in JavaScript?"
+- "Explain dependency injection"
+- "What is REST?"
 
-Before BK is useful, you need to add library sources:
+### Current Events
+Use web search:
+- "What's new in Next.js 15?"
+- "Latest release notes for TypeScript"
+- "Security advisory for npm packages"
 
+---
+
+## Setup: Index Your Dependencies
+
+BK only knows what you've indexed. Add your key dependencies:
+
+```bash
+# Get suggestions based on package.json
+/bluera-knowledge:suggest
+
+# Add important libraries
+/bluera-knowledge:add-repo https://github.com/expressjs/express
+/bluera-knowledge:add-repo https://github.com/honojs/hono
+
+# Index local docs
+/bluera-knowledge:add-folder ./docs --name=project-docs
+
+# Verify what's indexed
+/bluera-knowledge:stores
 ```
-/bk:suggest                  # Get recommendations
-/bk:add-repo <url> --name=<lib>   # Add important libs
-/bk:stores                   # Verify what's indexed
-```
+
+---
+
+## Quick Reference
+
+| Question Pattern | Use |
+|-----------------|-----|
+| "How does [library] work..." | BK |
+| "What does [library function] do..." | BK |
+| "What options/params does [library] accept..." | BK |
+| "What errors can [library] throw..." | BK |
+| "How should I use [library API]..." | BK |
+| "What changed in [library version]..." | BK |
+| "How do I integrate [library]..." | BK |
+| "Where is [thing] in OUR code..." | Grep/Read |
+| "What is [general concept]..." | Training data |
+| "What's new in [library] today..." | Web search |
+
+---
 
 ## Mental Model
 
 ```
-Current Project Files → Grep/Read directly
-           vs
-Library Sources (Vue, Pydantic, etc.) → BK (vector search OR Grep/Read)
+External Code (libraries, deps, specs)  →  Query BK
+Your Project Code                       →  Grep/Read directly
+General Knowledge                       →  Use training data
+Breaking News                           →  Web search
 ```
 
-BK gives you both ways to access library sources:
-1. Semantic search for discovery
-2. Grep/Read for precision
-
-Use whichever works best for your question!
+BK is cheap, fast, and authoritative. When in doubt about a library, query BK.

package/tests/integration/mcp.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
+import { spawn } from 'node:child_process';
+import { rm, mkdtemp, writeFile, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as readline from 'node:readline';
+
+/**
+ * MCP Server Integration Tests
+ *
+ * Tests that the MCP server actually starts and accepts JSON-RPC messages.
+ * Unlike unit tests that mock runMCPServer, these tests spawn a real
+ * MCP server process and communicate via stdin/stdout.
+ */
+describe('MCP Integration', () => {
+  let tempDir: string;
+  let testFilesDir: string;
+
+  beforeAll(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'mcp-test-'));
+    testFilesDir = join(tempDir, 'files');
+    await mkdir(testFilesDir, { recursive: true });
+    await writeFile(
+      join(testFilesDir, 'test.md'),
+      '# Test Document\n\nContent for MCP integration testing.'
+    );
+  }, 30000);
+
+  afterAll(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  interface JSONRPCResponse {
+    jsonrpc: string;
+    id: number;
+    result?: unknown;
+    error?: { code: number; message: string };
+  }
+
+  interface MCPClient {
+    proc: ChildProcess;
+    sendRequest: (method: string, params?: Record<string, unknown>) => Promise<JSONRPCResponse>;
+    close: () => void;
+  }
+
+  /**
+   * Start the MCP server and return a client with message helpers
+   */
+  function startMCPServer(): MCPClient {
+    const proc = spawn('node', ['dist/mcp/server.js'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        PROJECT_ROOT: tempDir,
+        DATA_DIR: join(tempDir, 'data'),
+        CONFIG_PATH: join(tempDir, 'config.json'),
+      },
+    });
+
+    // Set up a single readline interface for the entire process lifetime
+    const rl = readline.createInterface({ input: proc.stdout! });
+    const pendingRequests = new Map<
+      number,
+      { resolve: (r: JSONRPCResponse) => void; reject: (e: Error) => void }
+    >();
+    let requestId = 0;
+
+    rl.on('line', (line: string) => {
+      try {
+        const response = JSON.parse(line) as JSONRPCResponse;
+        const pending = pendingRequests.get(response.id);
+        if (pending !== undefined) {
+          pendingRequests.delete(response.id);
+          pending.resolve(response);
+        }
+      } catch {
+        // Ignore non-JSON lines (like log output)
+      }
+    });
+
+    return {
+      proc,
+      sendRequest: (
+        method: string,
+        params: Record<string, unknown> = {}
+      ): Promise<JSONRPCResponse> => {
+        return new Promise((resolve, reject) => {
+          if (proc.stdin === null) {
+            reject(new Error('Process stdin not available'));
+            return;
+          }
+
+          const id = ++requestId;
+          const timeout = setTimeout(() => {
+            pendingRequests.delete(id);
+            reject(new Error(`Timeout waiting for response to ${method}`));
+          }, 30000);
+
+          pendingRequests.set(id, {
+            resolve: (r) => {
+              clearTimeout(timeout);
+              resolve(r);
+            },
+            reject: (e) => {
+              clearTimeout(timeout);
+              reject(e);
+            },
+          });
+
+          const request = JSON.stringify({
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+          });
+
+          proc.stdin.write(request + '\n');
+        });
+      },
+      close: (): void => {
+        rl.close();
+        proc.kill('SIGTERM');
+      },
+    };
+  }
+
+  /**
+   * Wait for process to be ready
+   */
+  async function waitForReady(client: MCPClient, timeoutMs = 10000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Timeout waiting for MCP server to start'));
+      }, timeoutMs);
+
+      // MCP servers typically become ready quickly
+      // Give it a moment to initialize
+      setTimeout(() => {
+        clearTimeout(timeout);
+        resolve();
+      }, 1000);
+
+      client.proc.on('error', (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+
+      client.proc.on('exit', (code) => {
+        clearTimeout(timeout);
+        if (code !== 0 && code !== null) {
+          reject(new Error(`MCP server exited with code ${code}`));
+        }
+      });
+    });
+  }
+
+  let mcpClient: MCPClient | null = null;
+
+  afterEach(async () => {
+    // Clean up MCP client if still running
+    if (mcpClient !== null) {
+      mcpClient.close();
+      await new Promise<void>((resolve) => {
+        if (mcpClient !== null) {
+          mcpClient.proc.on('exit', () => resolve());
+          setTimeout(() => {
+            if (mcpClient !== null) {
+              mcpClient.proc.kill('SIGKILL');
+            }
+            resolve();
+          }, 2000);
+        } else {
+          resolve();
+        }
+      });
+      mcpClient = null;
+    }
+  });
+
+  it('starts, lists tools, and handles tool execution', async () => {
+    mcpClient = startMCPServer();
+    await waitForReady(mcpClient);
+
+    // 1. Initialize
+    const initResponse = await mcpClient.sendRequest('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'test-client', version: '1.0.0' },
+    });
+
+    expect(initResponse.jsonrpc).toBe('2.0');
+    expect(initResponse.error).toBeUndefined();
+    expect(initResponse.result).toBeDefined();
+
+    const initResult = initResponse.result as {
+      protocolVersion: string;
+      serverInfo: { name: string; version: string };
+      capabilities: { tools: Record<string, unknown> };
+    };
+    expect(initResult.serverInfo.name).toBe('bluera-knowledge');
+    expect(initResult.capabilities.tools).toBeDefined();
+
+    // 2. List tools
+    const toolsResponse = await mcpClient.sendRequest('tools/list', {});
+
+    expect(toolsResponse.error).toBeUndefined();
+    expect(toolsResponse.result).toBeDefined();
+
+    const toolsResult = toolsResponse.result as {
+      tools: Array<{ name: string; description: string }>;
+    };
+    expect(Array.isArray(toolsResult.tools)).toBe(true);
+
+    const toolNames = toolsResult.tools.map((t) => t.name);
+    expect(toolNames).toContain('search');
+    expect(toolNames).toContain('get_full_context');
+    expect(toolNames).toContain('execute');
+
+    // 3. Call search tool
+    const searchResponse = await mcpClient.sendRequest('tools/call', {
+      name: 'search',
+      arguments: {
+        query: 'test query',
+        limit: 5,
+      },
+    });
+
+    expect(searchResponse.error).toBeUndefined();
+    expect(searchResponse.result).toBeDefined();
+
+    const searchResult = searchResponse.result as {
+      content: Array<{ type: string; text: string }>;
+    };
+    expect(Array.isArray(searchResult.content)).toBe(true);
+
+    // 4. Call execute with help command
+    const helpResponse = await mcpClient.sendRequest('tools/call', {
+      name: 'execute',
+      arguments: {
+        command: 'help',
+      },
+    });
+
+    expect(helpResponse.error).toBeUndefined();
+    expect(helpResponse.result).toBeDefined();
+
+    const helpResult = helpResponse.result as { content: Array<{ type: string; text: string }> };
+    expect(helpResult.content[0]?.text).toContain('Available commands');
+  }, 120000);
+});

package/tests/integration/serve.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { rm, mkdtemp, writeFile, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Serve Command Integration Tests
+ *
+ * Tests that the HTTP server actually starts, responds to requests,
+ * and shuts down cleanly. Unlike unit tests that mock the serve function,
+ * these tests spawn a real server process and make actual HTTP requests.
+ */
+describe('Serve Integration', () => {
+  let tempDir: string;
+  let testFilesDir: string;
+  let serverProcess: ChildProcess | null = null;
+  const TEST_PORT = 19877; // Use a unique port to avoid conflicts
+
+  beforeAll(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'serve-test-'));
+    testFilesDir = join(tempDir, 'files');
+    await mkdir(testFilesDir, { recursive: true });
+    await writeFile(
+      join(testFilesDir, 'test.md'),
+      '# Test Document\n\nContent for serve integration testing.'
+    );
+  }, 30000);
+
+  afterAll(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  afterEach(async () => {
+    // Clean up server process if still running
+    if (serverProcess !== null) {
+      serverProcess.kill('SIGTERM');
+      await new Promise<void>((resolve) => {
+        if (serverProcess !== null) {
+          serverProcess.on('exit', () => resolve());
+          // Force kill after timeout
+          setTimeout(() => {
+            if (serverProcess !== null) {
+              serverProcess.kill('SIGKILL');
+            }
+            resolve();
+          }, 2000);
+        } else {
+          resolve();
+        }
+      });
+      serverProcess = null;
+    }
+  });
+
+  /**
+   * Start the serve command and wait for it to be ready
+   */
+  async function startServer(port: number): Promise<ChildProcess> {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(
+        'node',
+        ['dist/index.js', 'serve', '--port', String(port), '--data-dir', tempDir],
+        {
+          stdio: ['pipe', 'pipe', 'pipe'],
+        }
+      );
+
+      let resolved = false;
+      const timeout = setTimeout(() => {
+        if (!resolved) {
+          reject(new Error('Server startup timeout'));
+          proc.kill();
+        }
+      }, 30000);
+
+      proc.stdout?.on('data', (data: Buffer) => {
+        const output = data.toString();
+        if (output.includes('Starting server')) {
+          resolved = true;
+          clearTimeout(timeout);
+          // Give it a moment to actually start listening
+          setTimeout(() => resolve(proc), 500);
+        }
+      });
+
+      proc.stderr?.on('data', (data: Buffer) => {
+        // Log stderr but don't fail - some warnings are expected
+        console.error('Server stderr:', data.toString());
+      });
+
+      proc.on('error', (err) => {
+        if (!resolved) {
+          clearTimeout(timeout);
+          reject(err);
+        }
+      });
+
+      proc.on('exit', (code) => {
+        if (!resolved) {
+          clearTimeout(timeout);
+          reject(new Error(`Server exited with code ${String(code)}`));
+        }
+      });
+    });
+  }
+
+  /**
+   * Make an HTTP request with timeout
+   */
+  async function fetchWithTimeout(
+    url: string,
+    options: RequestInit = {},
+    timeoutMs = 5000
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await fetch(url, { ...options, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  describe('Server Startup and Health', () => {
+    it('starts server and responds to /health', async () => {
+      serverProcess = await startServer(TEST_PORT);
+
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT}/health`);
+      expect(response.ok).toBe(true);
+
+      const body = (await response.json()) as { status: string };
+      expect(body.status).toBe('ok');
+    }, 60000);
+
+    it('responds with CORS headers', async () => {
+      serverProcess = await startServer(TEST_PORT + 1);
+
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 1}/health`, {
+        method: 'OPTIONS',
+        headers: {
+          Origin: 'http://localhost:3000',
+          'Access-Control-Request-Method': 'GET',
+        },
+      });
+
+      // CORS preflight should succeed
+      expect(response.ok).toBe(true);
+    }, 60000);
+  });
+
+  describe('Store API', () => {
+    beforeEach(async () => {
+      serverProcess = await startServer(TEST_PORT + 2);
+    });
+
+    it('lists stores via GET /api/stores', async () => {
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 2}/api/stores`);
+      expect(response.ok).toBe(true);
+
+      const body = (await response.json()) as unknown[];
+      expect(Array.isArray(body)).toBe(true);
+    }, 60000);
+
+    it('creates store via POST /api/stores', async () => {
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 2}/api/stores`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: 'serve-test-store',
+          type: 'file',
+          path: testFilesDir,
+        }),
+      });
+
+      expect(response.status).toBe(201);
+      const body = (await response.json()) as { id: string; name: string };
+      expect(body.name).toBe('serve-test-store');
+      expect(body.id).toBeDefined();
+    }, 60000);
+
+    it('returns 400 for invalid store creation', async () => {
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 2}/api/stores`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: 'invalid-store',
+          type: 'file',
+          // Missing required 'path' for file type
+        }),
+      });
+
+      expect(response.status).toBe(400);
+    }, 60000);
+  });
+
+  describe('Search API', () => {
+    it('handles search request via POST /api/search', async () => {
+      serverProcess = await startServer(TEST_PORT + 3);
+
+      // Search with no stores indexed - should return empty results
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 3}/api/search`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          query: 'test query',
+          limit: 5,
+        }),
+      });
+
+      expect(response.ok).toBe(true);
+      const body = (await response.json()) as { results: unknown[] };
+      expect(body.results).toBeDefined();
+      expect(Array.isArray(body.results)).toBe(true);
+    }, 60000);
+
+    it('returns 400 for invalid search request', async () => {
+      serverProcess = await startServer(TEST_PORT + 4);
+
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 4}/api/search`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          // Missing required 'query'
+        }),
+      });
+
+      expect(response.status).toBe(400);
+    }, 60000);
+  });
+
+  describe('Graceful Shutdown', () => {
+    it('shuts down cleanly on SIGTERM', async () => {
+      serverProcess = await startServer(TEST_PORT + 5);
+
+      // Verify server is running
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 5}/health`);
+      expect(response.ok).toBe(true);
+
+      // Send SIGTERM
+      serverProcess.kill('SIGTERM');
+
+      // Wait for process to exit
+      const exitCode = await new Promise<number | null>((resolve) => {
+        if (serverProcess !== null) {
+          serverProcess.on('exit', (code) => resolve(code));
+          // Allow more time for graceful shutdown
+          setTimeout(() => resolve(null), 10000);
+        } else {
+          resolve(null);
+        }
+      });
+
+      // Process should exit cleanly (code 0) or be killed (null)
+      // On some systems the process may not exit with 0 due to async cleanup
+      expect(exitCode === 0 || exitCode === null).toBe(true);
+      serverProcess = null; // Already exited
+    }, 60000);
+  });
+});