@usewhisper/mcp-server 0.4.0 → 1.0.0

package/README.md

@@ -1,170 +1,103 @@
 # @usewhisper/mcp-server
 
-Model Context Protocol server for [Whisper Context API](https://usewhisper.dev) - Connect Claude Desktop to your knowledge base.
+Whisper MCP is the universal context bridge for coding agents. It connects Claude/Cursor/VS Code/Windsurf/Cline/Continue to fresh, indexed context with grounded retrieval and memory.
 
-**Version 0.2.0** - Now with 15 tools including SOTA Memory System, Oracle Research Mode, and Cost Optimization!
+## What's New (Major)
 
-## What is MCP?
+- Canonical namespaced tool surface (breaking rename)
+- Source multiplexer in `context.add_source` for `github|web|pdf|local|slack`
+- Auto-index by default for created sources
+- Runtime modes: `remote` (default), `local`, `auto`
+- Degraded retrieval behavior: lexical fallback with explicit `degraded_mode`
+- Scoped MCP config generator: `whisper-context-mcp scope ...`
+- Tool migration helper: `whisper-context-mcp --print-tool-map`
 
-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
+## Install
 
 ```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:
-
-### query_context
-Search your knowledge base with hybrid vector+keyword search, memory inclusion, and knowledge graph traversal.
-
-```
-Query your docs project for "authentication flow"
+npm i -g @usewhisper/mcp-server
 ```
 
-### add_memory
-Store persistent memories (facts, preferences, decisions) across conversations.
+## Required Environment
+
+- `WHISPER_API_KEY` (required)
+- `WHISPER_PROJECT` (optional default)
+- `WHISPER_BASE_URL` (optional, defaults to `https://context.usewhisper.dev`)
+- `WHISPER_MCP_MODE` (optional: `remote|local|auto`, default `remote`)
+- `WHISPER_LOCAL_ALLOWLIST` (optional comma-separated roots for local ingest)
+
+## Canonical Tools
+
+1. `context.list_projects`
+2. `context.list_sources`
+3. `context.add_source`
+4. `context.source_status`
+5. `context.query`
+6. `context.get_relevant`
+7. `context.claim_verify`
+8. `context.evidence_answer`
+9. `context.export_bundle`
+10. `context.import_bundle`
+11. `context.diff`
+12. `context.share`
+13. `memory.add`
+14. `memory.search`
+15. `memory.forget`
+16. `memory.consolidate`
+17. `research.oracle`
+18. `index.workspace_status`
+19. `index.workspace_run`
+20. `index.local_scan_ingest`
+21. `index.autosubscribe_deps`
+22. `code.search_text`
+23. `code.search_semantic`
+
+## Source Contract (`context.add_source`)
+
+Input:
+- `project?`, `type`, `name?`, `auto_index?` (default `true`), `metadata?`
+- `type=github`: `owner`, `repo`, `branch?`, `paths?`
+- `type=web`: `url`, `crawl_depth?`, `include_paths?`, `exclude_paths?`
+- `type=pdf`: `url?`, `file_path?`
+- `type=local`: `path`, `glob?`, `max_files?`
+- `type=slack`: `workspace_id?`, `channel_ids?`, `since?`
+
+Output:
+- `source_id`
+- `status` (`queued|indexing|ready|failed`)
+- `job_id`
+- `index_started`
+- `warnings[]`
+
+## Scoped MCP Generator
 
-```
-Remember that I prefer TypeScript over JavaScript
-```
-
-### search_memories
-Recall facts and preferences from previous interactions.
-
-```
-What programming languages do I prefer?
+```bash
+whisper-context-mcp scope --project my-project --source github --client claude
 ```
 
-### list_projects
-List all available context projects.
+Optional write:
 
-### 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
+```bash
+whisper-context-mcp scope --project my-project --source github --client vscode --write "$HOME/.config/Code/User/mcp.json"
 ```
 
-### track_conversation
-Record conversation messages for context tracking.
-
-### get_conversation
-Retrieve conversation history for a session.
-
-## Usage Examples
+## Breaking Rename Migration
 
-Once configured, you can chat with Claude Desktop naturally:
+Print full map:
 
+```bash
+whisper-context-mcp --print-tool-map
 ```
-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
+This release removes legacy un-namespaced tool names.
 
-## Links
+## Security Defaults
 
-- [Documentation](https://docs.usewhisper.dev/mcp)
-- [MCP Protocol](https://modelcontextprotocol.io)
-- [GitHub](https://github.com/usewhisper/whisper)
-- [Website](https://usewhisper.dev)
+Local ingest (`index.local_scan_ingest` and `type=local`) enforces:
+- allowlisted roots
+- secret/sensitive path filters (`.env`, `.pem`, `.key`, `.aws`, `.ssh`, build artifacts)
+- content redaction pass for likely secrets
 
 ## License
 
-MIT
+MIT