@usewhisper/mcp-server 0.4.0 → 0.5.0

package/README.md

@@ -2,169 +2,197 @@
 
 Model Context Protocol server for [Whisper Context API](https://usewhisper.dev) - Connect Claude Desktop to your knowledge base.
 
-**Version 0.2.0** - Now with 15 tools including SOTA Memory System, Oracle Research Mode, and Cost Optimization!
-
-## What is MCP?
-
-The Model Context Protocol (MCP) allows Claude Desktop to connect directly to external knowledge sources and tools. This server gives Claude Desktop access to your Whisper Context projects, enabling seamless RAG-powered conversations with advanced memory and research capabilities.
-
-## Installation
-
-```bash
-npm install -g @usewhisper/mcp-server
-```
-
-## Setup
-
-### 1. Get Your API Key
-
-Get your Whisper API key from the [dashboard](https://usewhisper.dev/dashboard).
-
-### 2. Configure Claude Desktop
-
-Add to your Claude Desktop config file:
-
-**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "whisper-context": {
-      "command": "whisper-context-mcp",
-      "env": {
-        "WHISPER_API_KEY": "wctx_...",
-        "WHISPER_PROJECT": "my-project"
-      }
-    }
-  }
-}
-```
-
-**Optional environment variables:**
-- `WHISPER_BASE_URL`: Custom API endpoint (defaults to `https://context.usewhisper.dev`)
-
-### 3. Restart Claude Desktop
-
-After configuration, restart Claude Desktop. The MCP server will appear in the bottom-right corner.
+Whisper makes code agents refuse unsupported claims about your codebase by combining retrieval, claim verification, and evidence-locked answering.
 
+**Version 0.2.0** - Now with 15 tools including SOTA Memory System, Oracle Research Mode, and Cost Optimization!
+
+## What is MCP?
+
+The Model Context Protocol (MCP) allows Claude Desktop to connect directly to external knowledge sources and tools. This server gives Claude Desktop access to your Whisper Context projects, enabling seamless RAG-powered conversations with advanced memory and research capabilities.
+
+## Installation
+
+```bash
+npm install -g @usewhisper/mcp-server
+```
+
+## Setup
+
+### 1. Get Your API Key
+
+Get your Whisper API key from the [dashboard](https://usewhisper.dev/dashboard).
+
+### 2. Configure Claude Desktop
+
+Add to your Claude Desktop config file:
+
+**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "whisper-context": {
+      "command": "whisper-context-mcp",
+      "env": {
+        "WHISPER_API_KEY": "wctx_...",
+        "WHISPER_PROJECT": "my-project"
+      }
+    }
+  }
+}
+```
+
+**Optional environment variables:**
+- `WHISPER_BASE_URL`: Custom API endpoint (defaults to `https://context.usewhisper.dev`)
+
+### 3. Restart Claude Desktop
+
+After configuration, restart Claude Desktop. The MCP server will appear in the bottom-right corner.
+
 ## Available Tools
 
 Once connected, Claude Desktop gets access to these tools:
 
+### Trust pipeline (recommended first)
+
+1. `resolve_workspace`
+2. `repo_index_status`
+3. `get_relevant_context`
+4. `claim_verifier`
+5. `evidence_locked_answer`
+
 ### query_context
 Search your knowledge base with hybrid vector+keyword search, memory inclusion, and knowledge graph traversal.
-
-```
-Query your docs project for "authentication flow"
-```
-
+
+```
+Query your docs project for "authentication flow"
+```
+
 ### add_memory
 Store persistent memories (facts, preferences, decisions) across conversations.
-
-```
-Remember that I prefer TypeScript over JavaScript
-```
-
-### search_memories
-Recall facts and preferences from previous interactions.
-
-```
-What programming languages do I prefer?
-```
-
-### list_projects
-List all available context projects.
-
-### list_sources
-See all data sources connected to a project (GitHub, Notion, Confluence, etc).
-
-### add_context
-Add text content directly to your knowledge base.
-
-```
-Add this API documentation to my docs project
-```
-
-### track_conversation
-Record conversation messages for context tracking.
-
+
+```
+Remember that I prefer TypeScript over JavaScript
+```
+
+### search_memories
+Recall facts and preferences from previous interactions.
+
+```
+What programming languages do I prefer?
+```
+
+### list_projects
+List all available context projects.
+
+### list_sources
+See all data sources connected to a project (GitHub, Notion, Confluence, etc).
+
+### add_context
+Add text content directly to your knowledge base.
+
+```
+Add this API documentation to my docs project
+```
+
+### track_conversation
+Record conversation messages for context tracking.
+
 ### get_conversation
 Retrieve conversation history for a session.
 
-## Usage Examples
-
-Once configured, you can chat with Claude Desktop naturally:
-
-```
-You: "Query my engineering-docs project for how to deploy to production"
-Claude: [Uses query_context tool to search your docs]
-
-You: "Remember that our staging environment is at staging.example.com"
-Claude: [Uses add_memory to store this fact]
-
-You: "What projects do I have?"
-Claude: [Uses list_projects to show all your context projects]
-```
-
-## Features
-
-- **Semantic Search**: Vector embeddings + BM25 hybrid search
-- **Conversational Memory**: Persistent memories across sessions
-- **Knowledge Graph**: Graph-based context traversal
-- **Auto-sync Sources**: GitHub, Notion, Confluence, Slack, and 10+ more
-- **Direct Ingestion**: Add content directly from conversations
-- **Session Tracking**: Maintains conversation context
-
-## Architecture
-
-The MCP server connects to your Whisper Context API:
-- **Whisper Context API** for semantic search, memory, and knowledge graph
-- **Stdio Transport** for Claude Desktop communication
-- **Zero dependencies** on database or infrastructure
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `WHISPER_API_KEY` | Yes | Your Whisper API key (get from dashboard) |
-| `WHISPER_PROJECT` | Optional | Default project name/slug for all operations |
-| `WHISPER_BASE_URL` | Optional | Custom API endpoint (defaults to https://context.usewhisper.dev) |
-
-## Troubleshooting
-
-### Server not appearing in Claude Desktop
-
-1. Check the config file path is correct
-2. Verify JSON syntax is valid
-3. Restart Claude Desktop completely
-4. Check Claude Desktop logs: `~/Library/Logs/Claude/` (Mac) or `%APPDATA%\Claude\logs\` (Windows)
-
-### Connection errors
-
-- Verify your `WHISPER_API_KEY` is valid (starts with `wctx_`)
-- Check that you have network connectivity to the API
-- Ensure your API key has the necessary permissions
-
-### "Project not found" errors
-
-- Make sure your project name/slug is correct
-- Set `WHISPER_PROJECT` in config for a default project
-- Use `list_projects` tool to see all available projects
-
-### No results from queries
-
-- Make sure your project has data sources connected or documents ingested
-- Verify the project name/slug matches exactly
-- Check that sources have been synced successfully in the dashboard
-
-## Links
-
-- [Documentation](https://docs.usewhisper.dev/mcp)
-- [MCP Protocol](https://modelcontextprotocol.io)
-- [GitHub](https://github.com/usewhisper/whisper)
-- [Website](https://usewhisper.dev)
-
-## License
-
-MIT
+### get_relevant_context
+Core retrieval contract with ranked evidence payloads (`path:line` ready).
+
+### claim_verifier
+Checks a claim and returns `supported | partial | unsupported` with evidence spans.
+
+### evidence_locked_answer
+Returns a cited answer only when thresholds are met; otherwise returns explicit abstain payload.
+
+### forget
+Deletes or invalidates memories with immutable audit metadata.
+
+### export_context_bundle / import_context_bundle
+Round-trip project/workspace context in a portable bundle with checksum verification.
+
+### diff_context
+Deterministic change view anchored by `session_id`, `timestamp`, or `commit`.
+
+## Usage Examples
+
+Once configured, you can chat with Claude Desktop naturally:
+
+```
+You: "Query my engineering-docs project for how to deploy to production"
+Claude: [Uses query_context tool to search your docs]
+
+You: "Remember that our staging environment is at staging.example.com"
+Claude: [Uses add_memory to store this fact]
+
+You: "What projects do I have?"
+Claude: [Uses list_projects to show all your context projects]
+```
+
+## Features
+
+- **Semantic Search**: Vector embeddings + BM25 hybrid search
+- **Conversational Memory**: Persistent memories across sessions
+- **Knowledge Graph**: Graph-based context traversal
+- **Auto-sync Sources**: GitHub, Notion, Confluence, Slack, and 10+ more
+- **Direct Ingestion**: Add content directly from conversations
+- **Session Tracking**: Maintains conversation context
+
+## Architecture
+
+The MCP server connects to your Whisper Context API:
+- **Whisper Context API** for semantic search, memory, and knowledge graph
+- **Stdio Transport** for Claude Desktop communication
+- **Zero dependencies** on database or infrastructure
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `WHISPER_API_KEY` | Yes | Your Whisper API key (get from dashboard) |
+| `WHISPER_PROJECT` | Optional | Default project name/slug for all operations |
+| `WHISPER_BASE_URL` | Optional | Custom API endpoint (defaults to https://context.usewhisper.dev) |
+
+## Troubleshooting
+
+### Server not appearing in Claude Desktop
+
+1. Check the config file path is correct
+2. Verify JSON syntax is valid
+3. Restart Claude Desktop completely
+4. Check Claude Desktop logs: `~/Library/Logs/Claude/` (Mac) or `%APPDATA%\Claude\logs\` (Windows)
+
+### Connection errors
+
+- Verify your `WHISPER_API_KEY` is valid (starts with `wctx_`)
+- Check that you have network connectivity to the API
+- Ensure your API key has the necessary permissions
+
+### "Project not found" errors
+
+- Make sure your project name/slug is correct
+- Set `WHISPER_PROJECT` in config for a default project
+- Use `list_projects` tool to see all available projects
+
+### No results from queries
+
+- Make sure your project has data sources connected or documents ingested
+- Verify the project name/slug matches exactly
+- Check that sources have been synced successfully in the dashboard
+
+## Links
+
+- [Documentation](https://docs.usewhisper.dev/mcp)
+- [MCP Protocol](https://modelcontextprotocol.io)
+- [GitHub](https://github.com/usewhisper/whisper)
+- [Website](https://usewhisper.dev)
+
+## License
+
+MIT