@usewhisper/mcp-server

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

What's New in v2.6

• Automatic project, user, and session scope defaults for MCP retrieval and memory operations.
• context.query can use the automatic agent runtime by default when the caller has not requested manual-only filters.
• URL and domain-style retrieval requests now isolate matching sources better in shared projects.
• MCP memory operations now default to pending/session-aware reads and writes when compatible.

Install

npm i -g @usewhisper/mcp-server

Terminal vs MCP

Use the terminal commands only to install the server, print migration info, or generate client config. Once the server is running, agents should call MCP tools like search, remember, learn, and share_context, not shell commands.

Required Environment

• WHISPER_API_KEY (required, use your wsk_* API key)
• WHISPER_PROJECT (optional default)
• WHISPER_BASE_URL (optional, defaults to https://context.usewhisper.dev)
• WHISPER_MCP_MODE (optional: remote|local|auto, recommended auto)
• 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)

Example values:

WHISPER_API_KEY=wsk_your_api_key_here
WHISPER_PROJECT=my-project
WHISPER_BASE_URL=https://context.usewhisper.dev

Example shell setup:

export WHISPER_API_KEY="wsk_your_api_key_here"
export WHISPER_PROJECT="my-project"
export WHISPER_BASE_URL="https://context.usewhisper.dev"

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 (compatibility alias; prefer context.query)
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
24. index.auto_repair
25. fix

Agent-Friendly Primary Verbs

These verbs are the primary MCP interface for agents. Namespaced tools remain available as compatibility and advanced surfaces.

• search -> exact fetch by id, semantic retrieval by query, or hybrid retrieval when both are present
• fix -> index.auto_repair for deterministic setup/retrieval repair
• 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
• remember -> memory.add
• record -> memory.ingest_conversation
• learn -> context.add_text | context.add_source | context.add_document
• share_context -> context.share

index remains available as an advanced/admin compatibility tool for indexing jobs and workspace refresh operations.

search behavior

search is the only primary retrieval verb.

• search({ id }) returns an exact memory fetch
• search({ query }) returns semantic retrieval
• search({ id, query }) returns the exact memory plus related retrieval context
• search({}) is invalid and returns { "success": false, "error": { "code": "invalid_request", "message": "..." } }

All primary verbs return structured JSON text payloads. Success payloads begin with "success": true; failures use the shared { success: false, error: { code, message } } envelope.

All valid search calls return the same top-level payload shape:

{
  "success": true,
  "mode": "exact | semantic | hybrid",
  "query": "string | null",
  "id": "string | null",
  "exact_memory": {},
  "context": "string",
  "results": [],
  "count": 0,
  "degraded_mode": false,
  "degraded_reason": null,
  "warnings": []
}

Automatic Defaults

When compatible with the caller’s requested options, Whisper MCP now behaves like an implicit context layer instead of a raw tool database:

• context.query auto-attaches default project, user, and session scope
• compatible retrieval calls use automatic runtime-backed pre-retrieval
• memory writes and session ingest calls attach stable default scope automatically

If the caller explicitly requests manual query controls such as chunk_types, explicit graph traversal, or other narrow filters, MCP preserves those manual semantics instead of forcing automatic mode.

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

Print config to stdout:

whisper-context-mcp scope --project my-project --source github --client claude

OpenCode project config generation:

whisper-context-mcp scope --project my-project --source github --client opencode

Write the generated config to a file:

whisper-context-mcp scope --project my-project --source github --client vscode --write /absolute/path/to/mcp.json

Breaking Rename Migration

Print full map:

whisper-context-mcp --print-tool-map

This release removes legacy un-namespaced tool names.

Contract Metadata

Public API metadata is available at:

GET /v1/contracts/meta

It exposes:

• current contract version
• active surfaces (http, sdk, mcp)
• approved primary MCP verbs
• migration window and removal policy
• deprecated HTTP routes with replacement hints

It does not expose internal security checklist fields.

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:

npx whisper-wizard

Flow:

1. Run wizard and complete auth/project setup.
2. Add a source with MCP: context.add_source
3. Ask a grounded question: context.query or context.evidence_answer
4. If you selected OpenCode, wizard also updates opencode.json and creates .opencode/plugins/whisper-context.ts

OpenCode Plugin Notes

When using OpenCode, the plugin runtime adds two OpenCode-only helper tools:

• whisper_status
• whisper_flush_session

These are plugin tools, not MCP tools. Continue using Whisper MCP for retrieval and persistence verbs.

License

MIT