@usewhisper/mcp-server 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +168 -0
  2. package/dist/server.js +1648 -0
  3. package/dist/server.js.map +1 -0
  4. package/package.json +52 -0
package/README.md ADDED
@@ -0,0 +1,168 @@
1
+ # @usewhisper/mcp-server
2
+
3
+ Model Context Protocol server for [Whisper Context API](https://usewhisper.dev) - Connect Claude Desktop to your knowledge base.
4
+
5
+ ## What is MCP?
6
+
7
+ 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.
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ npm install -g @usewhisper/mcp-server
13
+ ```
14
+
15
+ ## Setup
16
+
17
+ ### 1. Get Environment Variables
18
+
19
+ You'll need these environment variables:
20
+
21
+ ```env
22
+ DATABASE_URL=your_neon_postgres_url
23
+ OPENAI_API_KEY=your_openai_key
24
+ WHISPER_ORG_ID=your_organization_id
25
+ ```
26
+
27
+ Get your Whisper credentials from the [dashboard](https://usewhisper.dev/dashboard).
28
+
29
+ ### 2. Configure Claude Desktop
30
+
31
+ Add to your Claude Desktop config file:
32
+
33
+ **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
34
+ **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
35
+
36
+ ```json
37
+ {
38
+ "mcpServers": {
39
+ "whisper-context": {
40
+ "command": "whisper-context-mcp",
41
+ "env": {
42
+ "DATABASE_URL": "postgresql://user:pass@host/db",
43
+ "OPENAI_API_KEY": "sk-...",
44
+ "WHISPER_ORG_ID": "org_..."
45
+ }
46
+ }
47
+ }
48
+ }
49
+ ```
50
+
51
+ ### 3. Restart Claude Desktop
52
+
53
+ After configuration, restart Claude Desktop. The MCP server will appear in the bottom-right corner.
54
+
55
+ ## Available Tools
56
+
57
+ Once connected, Claude Desktop gets access to these tools:
58
+
59
+ ### query_context
60
+ Search your knowledge base with hybrid vector+keyword search, memory inclusion, and knowledge graph traversal.
61
+
62
+ ```
63
+ Query your docs project for "authentication flow"
64
+ ```
65
+
66
+ ### add_memory
67
+ Store persistent memories (facts, preferences, decisions) across conversations.
68
+
69
+ ```
70
+ Remember that I prefer TypeScript over JavaScript
71
+ ```
72
+
73
+ ### search_memories
74
+ Recall facts and preferences from previous interactions.
75
+
76
+ ```
77
+ What programming languages do I prefer?
78
+ ```
79
+
80
+ ### list_projects
81
+ List all available context projects.
82
+
83
+ ### list_sources
84
+ See all data sources connected to a project (GitHub, Notion, Confluence, etc).
85
+
86
+ ### add_context
87
+ Add text content directly to your knowledge base.
88
+
89
+ ```
90
+ Add this API documentation to my docs project
91
+ ```
92
+
93
+ ### track_conversation
94
+ Record conversation messages for context tracking.
95
+
96
+ ### get_conversation
97
+ Retrieve conversation history for a session.
98
+
99
+ ## Usage Examples
100
+
101
+ Once configured, you can chat with Claude Desktop naturally:
102
+
103
+ ```
104
+ You: "Query my engineering-docs project for how to deploy to production"
105
+ Claude: [Uses query_context tool to search your docs]
106
+
107
+ You: "Remember that our staging environment is at staging.example.com"
108
+ Claude: [Uses add_memory to store this fact]
109
+
110
+ You: "What projects do I have?"
111
+ Claude: [Uses list_projects to show all your context projects]
112
+ ```
113
+
114
+ ## Features
115
+
116
+ - **Semantic Search**: Vector embeddings + BM25 hybrid search
117
+ - **Conversational Memory**: Persistent memories across sessions
118
+ - **Knowledge Graph**: Graph-based context traversal
119
+ - **Auto-sync Sources**: GitHub, Notion, Confluence, Slack, and 10+ more
120
+ - **Direct Ingestion**: Add content directly from conversations
121
+ - **Session Tracking**: Maintains conversation context
122
+
123
+ ## Architecture
124
+
125
+ The MCP server connects directly to your Whisper Context database using:
126
+ - **PostgreSQL + pgvector** for vector search
127
+ - **OpenAI Embeddings** for semantic understanding
128
+ - **Stdio Transport** for Claude Desktop communication
129
+
130
+ ## Environment Variables
131
+
132
+ | Variable | Required | Description |
133
+ |----------|----------|-------------|
134
+ | `DATABASE_URL` | Yes | PostgreSQL connection string |
135
+ | `OPENAI_API_KEY` | Yes | OpenAI API key for embeddings |
136
+ | `WHISPER_ORG_ID` | Yes | Your Whisper organization ID |
137
+
138
+ ## Troubleshooting
139
+
140
+ ### Server not appearing in Claude Desktop
141
+
142
+ 1. Check the config file path is correct
143
+ 2. Verify JSON syntax is valid
144
+ 3. Restart Claude Desktop completely
145
+ 4. Check Claude Desktop logs: `~/Library/Logs/Claude/` (Mac) or `%APPDATA%\Claude\logs\` (Windows)
146
+
147
+ ### Connection errors
148
+
149
+ - Verify your `DATABASE_URL` is correct and accessible
150
+ - Ensure your `OPENAI_API_KEY` is valid
151
+ - Check that `WHISPER_ORG_ID` matches your organization
152
+
153
+ ### No results from queries
154
+
155
+ - Make sure your project has data sources connected or documents ingested
156
+ - Verify the project name/slug matches exactly
157
+ - Check that sources have been synced successfully
158
+
159
+ ## Links
160
+
161
+ - [Documentation](https://docs.usewhisper.dev/mcp)
162
+ - [MCP Protocol](https://modelcontextprotocol.io)
163
+ - [GitHub](https://github.com/usewhisper/whisper)
164
+ - [Website](https://usewhisper.dev)
165
+
166
+ ## License
167
+
168
+ MIT