@usewhisper/mcp-server 0.5.0 → 1.3.0

package/README.md

@@ -1,198 +1,147 @@
 # @usewhisper/mcp-server
 
-Model Context Protocol server for [Whisper Context API](https://usewhisper.dev) - Connect Claude Desktop to your knowledge base.
-
-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"
-```
-
-### 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.
-
-### get_conversation
-Retrieve conversation history for a session.
-
-### 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
+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.
+
+## What's New (Major)
+
+- Canonical namespaced tool surface (breaking rename)
+- Source multiplexer in `context.add_source` for `github|web|pdf|local|slack|video`
+- 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`
+
+## Install
+
+```bash
+npm i -g @usewhisper/mcp-server
+```
+
+## 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)
+- `SLACK_BOT_TOKEN` (required for Slack connector runs)
+- `SLACK_CHANNEL_ID` (required for Slack connector runs)
+
+## Connector Status + Credentials
+
+| Connector | Status | Minimum required config/creds |
+|---|---|---|
+| GitHub | Production-ready | `type=github`, `owner`, `repo` (optional `token`, `branch`, `paths`) |
+| Web | Production-ready | `type=web`, `url` (optional `crawl_depth`, `include_paths`, `exclude_paths`) |
+| PDF | Production-ready | `type=pdf`, `url` or `file_path` |
+| Slack | Production-ready (requires Slack auth) | `type=slack`, `token`, `channel_ids[]` (optional `since`, `workspace_id`) |
+| Local | Production-ready | `type=local`, `path` (optional `glob`, `max_files`) |
+| Video | Production-ready | `type=video`, `url` (optional `platform`, `language`, `allow_stt_fallback`, `max_duration_minutes`, `max_chunks`) |
+
+## 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`
+
+## Agent-Friendly Aliases
+
+These aliases sit on top of the canonical namespaced tools and are easier for coding agents to pick correctly:
+
+- `search` -> `context.query`
+- `search_code` -> `code.search_semantic`
+- `grep` -> `code.search_text`
+- `read` -> local file read with optional line ranges
+- `explore` -> local repository tree browsing
+- `research` -> `research.oracle`
+- `index` -> source add or workspace refresh
+- `remember` -> `memory.add`
+- `recall` -> `memory.search`
+- `share_context` -> `context.share`
+
+## 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`: `token`, `channel_ids[]`, `workspace_id?`, `since?`, `auth_ref?`
+- `type=video`: `url`, `platform?`, `language?`, `allow_stt_fallback?`, `max_duration_minutes?`, `max_chunks?`
+
+Output:
+- `source_id`
+- `status` (`queued|indexing|ready|failed`)
+- `job_id`
+- `index_started`
+- `warnings[]`
+
+## Scoped MCP Generator
+
+```bash
+whisper-context-mcp scope --project my-project --source github --client claude
+```
+
+Optional write:
+
+```bash
+whisper-context-mcp scope --project my-project --source github --client vscode --write "$HOME/.config/Code/User/mcp.json"
+```
+
+## Breaking Rename Migration
+
+Print full map:
+
+```bash
+whisper-context-mcp --print-tool-map
+```
+
+This release removes legacy un-namespaced tool names.
+
+## Security Defaults
+
+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
+
+## 30-Second Demo
+
+One-command wizard + production MCP connectors + scoped config:
+
+```bash
+npx whisper-wizard
+```
+
+Flow:
+1. Run wizard and complete auth/project setup.
+2. Add a source with MCP:
+`context.add_source` (for example GitHub/Web/PDF/Slack/Local/Video).
+3. Ask a grounded question:
+`context.query` or `context.evidence_answer` for citation-locked output.
+
+## License
+
+MIT