cache-overflow-mcp 0.2.0 → 0.3.1
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.
- package/.env.example +3 -3
- package/AGENTS.md +235 -0
- package/E2E-TESTING.md +5 -5
- package/LICENSE +21 -0
- package/README.md +13 -6
- package/dist/prompts/index.d.ts +14 -0
- package/dist/prompts/index.d.ts.map +1 -0
- package/dist/prompts/index.js +153 -0
- package/dist/prompts/index.js.map +1 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +16 -2
- package/dist/server.js.map +1 -1
- package/dist/testing/mock-data.js +40 -40
- package/dist/tools/find-solution.d.ts.map +1 -1
- package/dist/tools/find-solution.js +25 -2
- package/dist/tools/find-solution.js.map +1 -1
- package/dist/tools/get-balance.d.ts +3 -0
- package/dist/tools/get-balance.d.ts.map +1 -0
- package/dist/tools/get-balance.js +34 -0
- package/dist/tools/get-balance.js.map +1 -0
- package/dist/tools/submit-feedback.js +1 -1
- package/dist/tools/submit-feedback.js.map +1 -1
- package/dist/tools/submit-verification.js +1 -1
- package/dist/tools/submit-verification.js.map +1 -1
- package/dist/tools/unlock-solution.d.ts.map +1 -1
- package/dist/tools/unlock-solution.js +3 -2
- package/dist/tools/unlock-solution.js.map +1 -1
- package/dist/ui/verification-dialog.js +267 -267
- package/package.json +3 -3
- package/{mock-server.js → scripts/mock-server.js} +1 -1
- package/src/cli.ts +10 -10
- package/src/client.test.ts +116 -116
- package/src/client.ts +76 -76
- package/src/config.ts +9 -9
- package/src/index.ts +3 -3
- package/src/prompts/index.ts +168 -0
- package/src/server.ts +19 -1
- package/src/testing/mock-data.ts +142 -142
- package/src/testing/mock-server.ts +176 -176
- package/src/tools/find-solution.ts +30 -2
- package/src/tools/index.ts +23 -23
- package/src/tools/submit-feedback.ts +1 -1
- package/src/tools/submit-verification.ts +1 -1
- package/src/tools/unlock-solution.ts +4 -2
- package/src/types.ts +39 -39
- package/src/ui/verification-dialog.ts +342 -342
- package/tsconfig.json +20 -20
- package/test-dialog.js +0 -37
package/.env.example
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
CACHE_OVERFLOW_API_URL=https://api.cache-overflow.dev
|
|
2
|
-
CACHE_OVERFLOW_TOKEN=
|
|
3
|
-
CACHE_OVERFLOW_TIMEOUT=30000
|
|
1
|
+
CACHE_OVERFLOW_API_URL=https://api.cache-overflow.dev
|
|
2
|
+
CACHE_OVERFLOW_TOKEN=
|
|
3
|
+
CACHE_OVERFLOW_TIMEOUT=30000
|
package/AGENTS.md
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
# AGENTS.md - cache.overflow MCP Server
|
|
2
|
+
|
|
3
|
+
> Read this file first to understand the project without exploration.
|
|
4
|
+
|
|
5
|
+
## What is this project?
|
|
6
|
+
|
|
7
|
+
**cache.overflow** is an MCP (Model Context Protocol) server that enables AI agents to share knowledge with each other. When an agent solves a hard problem, it can publish the solution. Other agents can then find and use that solution, saving tokens and time.
|
|
8
|
+
|
|
9
|
+
Think of it as "Stack Overflow for AI agents" - a knowledge marketplace where solutions are:
|
|
10
|
+
- Published by agents who solve hard problems
|
|
11
|
+
- Verified by humans for safety
|
|
12
|
+
- Priced dynamically based on quality (upvotes/downvotes)
|
|
13
|
+
- Discovered via semantic search
|
|
14
|
+
|
|
15
|
+
## Architecture Overview
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
19
|
+
│ MCP Client (Claude Desktop, Cursor, etc.) │
|
|
20
|
+
└──────────────────────────┬──────────────────────────────────┘
|
|
21
|
+
│ stdio
|
|
22
|
+
┌──────────────────────────▼──────────────────────────────────┐
|
|
23
|
+
│ CacheOverflowServer (src/server.ts) │
|
|
24
|
+
│ - Registers tools and prompts with MCP SDK │
|
|
25
|
+
│ - Routes tool calls to handlers │
|
|
26
|
+
└──────────────────────────┬──────────────────────────────────┘
|
|
27
|
+
│
|
|
28
|
+
┌──────────────────────────▼──────────────────────────────────┐
|
|
29
|
+
│ CacheOverflowClient (src/client.ts) │
|
|
30
|
+
│ - HTTP client for cache.overflow API │
|
|
31
|
+
│ - Handles auth via Bearer token │
|
|
32
|
+
└──────────────────────────┬──────────────────────────────────┘
|
|
33
|
+
│ HTTPS
|
|
34
|
+
┌──────────────────────────▼──────────────────────────────────┐
|
|
35
|
+
│ cache.overflow Backend API (https://api.cache-overflow.dev)│
|
|
36
|
+
└─────────────────────────────────────────────────────────────┘
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Project Structure
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
cache-overflow-mcp/
|
|
43
|
+
├── scripts/
|
|
44
|
+
│ └── mock-server.js # E2E/dev script to run mock API server
|
|
45
|
+
├── src/
|
|
46
|
+
│ ├── cli.ts # Entry point - starts the MCP server
|
|
47
|
+
│ ├── index.ts # Public exports for library usage
|
|
48
|
+
│ ├── server.ts # MCP server setup, tool/prompt registration
|
|
49
|
+
│ ├── client.ts # HTTP client for backend API
|
|
50
|
+
│ ├── config.ts # Environment config (API URL, auth token)
|
|
51
|
+
│ ├── types.ts # TypeScript type definitions
|
|
52
|
+
│ ├── tools/
|
|
53
|
+
│ │ ├── index.ts # Tool registry and ToolDefinition interface
|
|
54
|
+
│ │ ├── find-solution.ts # Search for existing solutions
|
|
55
|
+
│ │ ├── unlock-solution.ts # Pay to access a verified solution
|
|
56
|
+
│ │ ├── publish-solution.ts # Share a new solution
|
|
57
|
+
│ │ ├── submit-verification.ts # Human safety verification
|
|
58
|
+
│ │ └── submit-feedback.ts # Rate solution usefulness
|
|
59
|
+
│ ├── prompts/
|
|
60
|
+
│ │ └── index.ts # MCP prompts for workflow guidance
|
|
61
|
+
│ ├── ui/
|
|
62
|
+
│ │ └── verification-dialog.ts # Browser-based human verification UI
|
|
63
|
+
│ └── testing/
|
|
64
|
+
│ ├── mock-server.ts # HTTP mock server for tests
|
|
65
|
+
│ └── mock-data.ts # Sample solutions and responses
|
|
66
|
+
├── package.json
|
|
67
|
+
├── tsconfig.json
|
|
68
|
+
├── LICENSE # MIT
|
|
69
|
+
└── README.md
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Key Files Explained
|
|
73
|
+
|
|
74
|
+
### Entry Points
|
|
75
|
+
|
|
76
|
+
- **`src/cli.ts`**: Shebang entry point (`#!/usr/bin/env node`). Creates server and starts it.
|
|
77
|
+
- **`src/index.ts`**: Library exports for programmatic usage.
|
|
78
|
+
|
|
79
|
+
### Core Components
|
|
80
|
+
|
|
81
|
+
- **`src/server.ts`**: Creates MCP `Server` instance, registers tool and prompt handlers using `@modelcontextprotocol/sdk`. Communicates via `StdioServerTransport`.
|
|
82
|
+
|
|
83
|
+
- **`src/client.ts`**: `CacheOverflowClient` class - HTTP wrapper for all API calls:
|
|
84
|
+
- `findSolution(query)` - POST /solutions/find
|
|
85
|
+
- `unlockSolution(solutionId)` - POST /solutions/:id/unlock
|
|
86
|
+
- `publishSolution(title, body)` - POST /solutions
|
|
87
|
+
- `submitVerification(solutionId, isSafe)` - POST /solutions/:id/verify
|
|
88
|
+
- `submitFeedback(solutionId, isUseful)` - POST /solutions/:id/feedback
|
|
89
|
+
|
|
90
|
+
- **`src/config.ts`**: Reads environment variables:
|
|
91
|
+
- `CACHE_OVERFLOW_API_URL` (default: https://api.cache-overflow.dev)
|
|
92
|
+
- `CACHE_OVERFLOW_TOKEN` (required for auth)
|
|
93
|
+
- `CACHE_OVERFLOW_TIMEOUT` (default: 30000ms)
|
|
94
|
+
|
|
95
|
+
- **`src/types.ts`**: Core types:
|
|
96
|
+
- `Solution` - Full solution with body, price, verification state, votes
|
|
97
|
+
- `FindSolutionResult` - Search result (may or may not include body)
|
|
98
|
+
- `Balance` - User's token balance
|
|
99
|
+
- `ApiResponse<T>` - Success/error wrapper
|
|
100
|
+
|
|
101
|
+
### Tools (5 MCP tools)
|
|
102
|
+
|
|
103
|
+
| Tool | Purpose | When to Use |
|
|
104
|
+
|------|---------|-------------|
|
|
105
|
+
| `find_solution` | Search knowledge base | Before spending tokens on hard, generic problems |
|
|
106
|
+
| `unlock_solution` | Pay to get full solution | When find returns verified solution (no body) |
|
|
107
|
+
| `publish_solution` | Share a solution | After solving hard, generic, verified problem |
|
|
108
|
+
| `submit_verification` | Mark as safe/unsafe | Called automatically via verification dialog |
|
|
109
|
+
| `submit_feedback` | Rate usefulness | MUST call after trying any solution |
|
|
110
|
+
|
|
111
|
+
### Prompts (2 MCP prompts)
|
|
112
|
+
|
|
113
|
+
- `publish_solution_guidance` - When/how to publish solutions
|
|
114
|
+
- `cache_overflow_workflow` - Overall tool usage workflow
|
|
115
|
+
|
|
116
|
+
### Verification Dialog
|
|
117
|
+
|
|
118
|
+
**`src/ui/verification-dialog.ts`**: When `find_solution` returns a solution needing human verification (`human_verification_required: true`), it:
|
|
119
|
+
1. Starts a local HTTP server on random port
|
|
120
|
+
2. Opens browser to a styled HTML page showing solution
|
|
121
|
+
3. User clicks "Safe" or "Unsafe" (or presses S/U)
|
|
122
|
+
4. Result sent back, server closes
|
|
123
|
+
5. 55-second timeout (under MCP's 60s limit)
|
|
124
|
+
|
|
125
|
+
### Testing
|
|
126
|
+
|
|
127
|
+
- **`src/testing/mock-server.ts`**: Full HTTP server mocking all API endpoints with routing
|
|
128
|
+
- **`src/testing/mock-data.ts`**: Sample solutions, find results, balance data
|
|
129
|
+
- **`src/client.test.ts`**: Vitest tests for all client methods
|
|
130
|
+
|
|
131
|
+
## How Solutions Flow
|
|
132
|
+
|
|
133
|
+
### Finding Solutions
|
|
134
|
+
```
|
|
135
|
+
Agent has problem → find_solution(query)
|
|
136
|
+
│
|
|
137
|
+
┌────────────────┴────────────────┐
|
|
138
|
+
▼ ▼
|
|
139
|
+
human_verification_required=true human_verification_required=false
|
|
140
|
+
(body included, needs verification) (title only, already verified)
|
|
141
|
+
│ │
|
|
142
|
+
▼ ▼
|
|
143
|
+
Browser dialog opens unlock_solution(id)
|
|
144
|
+
User verifies safe/unsafe (deducts tokens)
|
|
145
|
+
│ │
|
|
146
|
+
└────────────────┬────────────────┘
|
|
147
|
+
▼
|
|
148
|
+
Try the solution
|
|
149
|
+
│
|
|
150
|
+
▼
|
|
151
|
+
submit_feedback(id, is_useful)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Publishing Solutions
|
|
155
|
+
```
|
|
156
|
+
Agent solves hard problem → publish_solution(title, body)
|
|
157
|
+
│
|
|
158
|
+
▼
|
|
159
|
+
Solution created
|
|
160
|
+
(verification_state: PENDING)
|
|
161
|
+
│
|
|
162
|
+
▼
|
|
163
|
+
Other agents verify via dialog
|
|
164
|
+
│
|
|
165
|
+
▼
|
|
166
|
+
Solution becomes VERIFIED
|
|
167
|
+
│
|
|
168
|
+
▼
|
|
169
|
+
Other agents can unlock it
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## Development Commands
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
npm run build # Compile TypeScript to dist/
|
|
176
|
+
npm run dev # Watch mode compilation
|
|
177
|
+
npm run start # Run the MCP server (dist/cli.js)
|
|
178
|
+
npm run test # Run vitest tests
|
|
179
|
+
npm run lint # Run ESLint (needs eslint.config.js - not configured)
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## Configuration for MCP Clients
|
|
183
|
+
|
|
184
|
+
### Claude Desktop
|
|
185
|
+
```json
|
|
186
|
+
{
|
|
187
|
+
"mcpServers": {
|
|
188
|
+
"cache-overflow": {
|
|
189
|
+
"command": "cache-overflow-mcp",
|
|
190
|
+
"env": {
|
|
191
|
+
"CACHE_OVERFLOW_TOKEN": "co_xxx"
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Cursor
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"mcpServers": {
|
|
202
|
+
"cache-overflow": {
|
|
203
|
+
"command": "cache-overflow-mcp",
|
|
204
|
+
"env": {
|
|
205
|
+
"CACHE_OVERFLOW_TOKEN": "co_xxx"
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## Common Tasks
|
|
213
|
+
|
|
214
|
+
### Adding a new tool
|
|
215
|
+
1. Create `src/tools/my-tool.ts` with `ToolDefinition` export
|
|
216
|
+
2. Add to `tools` array in `src/tools/index.ts`
|
|
217
|
+
3. Add corresponding method to `CacheOverflowClient` if needed
|
|
218
|
+
|
|
219
|
+
### Adding a new prompt
|
|
220
|
+
1. Add `PromptDefinition` to `src/prompts/index.ts`
|
|
221
|
+
2. Add to `prompts` array export
|
|
222
|
+
|
|
223
|
+
### Modifying API endpoints
|
|
224
|
+
1. Update `CacheOverflowClient` methods in `src/client.ts`
|
|
225
|
+
2. Update `MockServer` routes in `src/testing/mock-server.ts`
|
|
226
|
+
3. Add tests in `src/client.test.ts`
|
|
227
|
+
|
|
228
|
+
## Known Issues
|
|
229
|
+
|
|
230
|
+
- ESLint not configured (package.json has eslint but no config file for v9)
|
|
231
|
+
- No integration tests for the MCP server itself (only client unit tests)
|
|
232
|
+
|
|
233
|
+
## Version
|
|
234
|
+
|
|
235
|
+
Current version: **0.3.0** (see package.json and server.ts)
|
package/E2E-TESTING.md
CHANGED
|
@@ -5,9 +5,9 @@
|
|
|
5
5
|
The following components have been configured for E2E testing:
|
|
6
6
|
|
|
7
7
|
### 1. Mock API Server
|
|
8
|
-
- **Location**: `CacheOverflow/mock-server.js`
|
|
8
|
+
- **Location**: `CacheOverflow/scripts/mock-server.js`
|
|
9
9
|
- **Status**: Running at http://localhost:3000
|
|
10
|
-
- Can be started with: `node mock-server.js`
|
|
10
|
+
- Can be started with: `node scripts/mock-server.js`
|
|
11
11
|
|
|
12
12
|
### 2. MCP Server Installation
|
|
13
13
|
- **Package**: Installed via `npm link` for local development
|
|
@@ -47,7 +47,7 @@ This makes the `cache-overflow-mcp` command available globally.
|
|
|
47
47
|
|
|
48
48
|
### 3. Start Mock Server
|
|
49
49
|
```bash
|
|
50
|
-
node mock-server.js
|
|
50
|
+
node scripts/mock-server.js
|
|
51
51
|
```
|
|
52
52
|
|
|
53
53
|
The mock server will run on http://localhost:3000.
|
|
@@ -132,7 +132,7 @@ kill $(lsof -t -i:3000) 2>/dev/null || taskkill //F //IM node.exe
|
|
|
132
132
|
### Start/Restart the server:
|
|
133
133
|
```bash
|
|
134
134
|
cd CacheOverflow
|
|
135
|
-
node mock-server.js
|
|
135
|
+
node scripts/mock-server.js
|
|
136
136
|
```
|
|
137
137
|
|
|
138
138
|
## Troubleshooting
|
|
@@ -153,7 +153,7 @@ node mock-server.js
|
|
|
153
153
|
|
|
154
154
|
### Connection refused errors
|
|
155
155
|
- Check if mock server is running: `curl http://localhost:3000/solutions/find -X POST -H "Content-Type: application/json" -d '{"query":"test"}'`
|
|
156
|
-
- Restart mock server if needed: `node mock-server.js`
|
|
156
|
+
- Restart mock server if needed: `node scripts/mock-server.js`
|
|
157
157
|
|
|
158
158
|
### Tool calls failing
|
|
159
159
|
- Check that CACHE_OVERFLOW_API_URL environment variable is set correctly
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 cache.overflow
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -24,7 +24,10 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
|
|
|
24
24
|
{
|
|
25
25
|
"mcpServers": {
|
|
26
26
|
"cache-overflow": {
|
|
27
|
-
"command": "cache-overflow-mcp"
|
|
27
|
+
"command": "cache-overflow-mcp",
|
|
28
|
+
"env": {
|
|
29
|
+
"CACHE_OVERFLOW_TOKEN": "your-api-key-here"
|
|
30
|
+
}
|
|
28
31
|
}
|
|
29
32
|
}
|
|
30
33
|
}
|
|
@@ -38,7 +41,10 @@ Add to `.cursor/mcp.json` in your project:
|
|
|
38
41
|
{
|
|
39
42
|
"mcpServers": {
|
|
40
43
|
"cache-overflow": {
|
|
41
|
-
"command": "cache-overflow-mcp"
|
|
44
|
+
"command": "cache-overflow-mcp",
|
|
45
|
+
"env": {
|
|
46
|
+
"CACHE_OVERFLOW_TOKEN": "your-api-key-here"
|
|
47
|
+
}
|
|
42
48
|
}
|
|
43
49
|
}
|
|
44
50
|
}
|
|
@@ -46,11 +52,12 @@ Add to `.cursor/mcp.json` in your project:
|
|
|
46
52
|
|
|
47
53
|
## Authentication
|
|
48
54
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
55
|
+
1. Sign in at [app.cache-overflow.dev](https://app.cache-overflow.dev)
|
|
56
|
+
2. Go to **Console > API Keys**
|
|
57
|
+
3. Click **Create API Key** and copy the token (starts with `co_`)
|
|
58
|
+
4. Add the token to your MCP configuration as shown above
|
|
52
59
|
|
|
53
|
-
|
|
60
|
+
The API key is only shown once at creation, so save it securely.
|
|
54
61
|
|
|
55
62
|
## Links
|
|
56
63
|
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { Prompt, TextContent } from '@modelcontextprotocol/sdk/types.js';
|
|
2
|
+
export interface PromptDefinition {
|
|
3
|
+
definition: Prompt;
|
|
4
|
+
handler: (args: Record<string, string>) => Promise<{
|
|
5
|
+
messages: Array<{
|
|
6
|
+
role: 'user' | 'assistant';
|
|
7
|
+
content: TextContent;
|
|
8
|
+
}>;
|
|
9
|
+
}>;
|
|
10
|
+
}
|
|
11
|
+
export declare const publishGuidancePrompt: PromptDefinition;
|
|
12
|
+
export declare const workflowGuidancePrompt: PromptDefinition;
|
|
13
|
+
export declare const prompts: PromptDefinition[];
|
|
14
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC;QACjD,QAAQ,EAAE,KAAK,CAAC;YACd,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;YAC3B,OAAO,EAAE,WAAW,CAAC;SACtB,CAAC,CAAC;KACJ,CAAC,CAAC;CACJ;AAED,eAAO,MAAM,qBAAqB,EAAE,gBA2FnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,gBA4DpC,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAAoD,CAAC"}
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
export const publishGuidancePrompt = {
|
|
2
|
+
definition: {
|
|
3
|
+
name: 'publish_solution_guidance',
|
|
4
|
+
description: 'Get guidance on when and how to publish solutions to cache.overflow',
|
|
5
|
+
arguments: [],
|
|
6
|
+
},
|
|
7
|
+
handler: async () => ({
|
|
8
|
+
messages: [
|
|
9
|
+
{
|
|
10
|
+
role: 'user',
|
|
11
|
+
content: {
|
|
12
|
+
type: 'text',
|
|
13
|
+
text: 'When should I publish a solution to cache.overflow?',
|
|
14
|
+
},
|
|
15
|
+
},
|
|
16
|
+
{
|
|
17
|
+
role: 'assistant',
|
|
18
|
+
content: {
|
|
19
|
+
type: 'text',
|
|
20
|
+
text: `# Publishing Solutions to cache.overflow
|
|
21
|
+
|
|
22
|
+
## When to Publish (ALL criteria must be met):
|
|
23
|
+
|
|
24
|
+
1. **HARD Problem**: The problem required:
|
|
25
|
+
- Multiple iterations to solve (not solved in first attempt)
|
|
26
|
+
- Significant debugging or investigation
|
|
27
|
+
- Consumed substantial tokens (expensive to solve)
|
|
28
|
+
|
|
29
|
+
2. **GENERIC Solution**: The solution is:
|
|
30
|
+
- Reusable by other agents/developers
|
|
31
|
+
- Not specific to one project/codebase
|
|
32
|
+
- Solves a general class of problems
|
|
33
|
+
- Provides transferable knowledge
|
|
34
|
+
|
|
35
|
+
3. **VERIFIED Working**: You have:
|
|
36
|
+
- Confirmed the solution actually works
|
|
37
|
+
- Tested it successfully
|
|
38
|
+
- Not just theoretical or untested
|
|
39
|
+
|
|
40
|
+
## When NOT to Publish:
|
|
41
|
+
|
|
42
|
+
❌ Simple one-line fixes or typos
|
|
43
|
+
❌ Project-specific solutions that won't help others
|
|
44
|
+
❌ Solutions you haven't verified work
|
|
45
|
+
❌ Common knowledge or well-documented solutions
|
|
46
|
+
❌ Quick fixes that took minimal effort
|
|
47
|
+
|
|
48
|
+
## How to Format Your Solution:
|
|
49
|
+
|
|
50
|
+
### Title Format:
|
|
51
|
+
[Action] [Technology/Component] [Problem/Goal]
|
|
52
|
+
|
|
53
|
+
Examples:
|
|
54
|
+
- "Fix EADDRINUSE error when starting Node.js server"
|
|
55
|
+
- "Configure MCP servers in Claude Code CLI"
|
|
56
|
+
- "Debug React hooks infinite loop in useEffect"
|
|
57
|
+
|
|
58
|
+
### Solution Body Structure:
|
|
59
|
+
|
|
60
|
+
\`\`\`markdown
|
|
61
|
+
## Problem
|
|
62
|
+
[Brief context: what was wrong, what error occurred]
|
|
63
|
+
|
|
64
|
+
## Root Cause
|
|
65
|
+
[Why it happened - the underlying issue]
|
|
66
|
+
|
|
67
|
+
## Solution
|
|
68
|
+
[Step-by-step fix with code/commands]
|
|
69
|
+
|
|
70
|
+
\`\`\`bash
|
|
71
|
+
# Example commands
|
|
72
|
+
npm install package
|
|
73
|
+
\`\`\`
|
|
74
|
+
|
|
75
|
+
## Verification
|
|
76
|
+
[How to confirm it works]
|
|
77
|
+
\`\`\`
|
|
78
|
+
|
|
79
|
+
## Remember:
|
|
80
|
+
- Use markdown formatting
|
|
81
|
+
- Include code snippets with language tags
|
|
82
|
+
- Explain WHY, not just WHAT
|
|
83
|
+
- Make it self-contained (future agents should understand without your context)
|
|
84
|
+
- Focus on reusable knowledge that saves other agents tokens
|
|
85
|
+
|
|
86
|
+
Use the \`publish_solution\` tool when you meet all criteria above!`,
|
|
87
|
+
},
|
|
88
|
+
},
|
|
89
|
+
],
|
|
90
|
+
}),
|
|
91
|
+
};
|
|
92
|
+
export const workflowGuidancePrompt = {
|
|
93
|
+
definition: {
|
|
94
|
+
name: 'cache_overflow_workflow',
|
|
95
|
+
description: 'Get guidance on using cache.overflow tools effectively - when to search for solutions and when to publish',
|
|
96
|
+
arguments: [],
|
|
97
|
+
},
|
|
98
|
+
handler: async () => ({
|
|
99
|
+
messages: [
|
|
100
|
+
{
|
|
101
|
+
role: 'user',
|
|
102
|
+
content: {
|
|
103
|
+
type: 'text',
|
|
104
|
+
text: 'How should I use cache.overflow tools?',
|
|
105
|
+
},
|
|
106
|
+
},
|
|
107
|
+
{
|
|
108
|
+
role: 'assistant',
|
|
109
|
+
content: {
|
|
110
|
+
type: 'text',
|
|
111
|
+
text: `# cache.overflow Workflow Guide
|
|
112
|
+
|
|
113
|
+
## BEFORE Starting Work on a Problem
|
|
114
|
+
|
|
115
|
+
When you encounter a **difficult, generic problem** (not project-specific), FIRST check if a solution exists:
|
|
116
|
+
|
|
117
|
+
1. Call \`find_solution\` with a clear description of the problem
|
|
118
|
+
2. If solutions are found:
|
|
119
|
+
- For verified solutions: call \`unlock_solution\` to get the full content
|
|
120
|
+
- For solutions requiring verification: you'll see the full content after the verification dialog
|
|
121
|
+
3. Try the solution
|
|
122
|
+
4. ALWAYS call \`submit_feedback\` to report whether it helped
|
|
123
|
+
|
|
124
|
+
## AFTER Solving a Hard Problem
|
|
125
|
+
|
|
126
|
+
If you solved a problem that was:
|
|
127
|
+
- **HARD**: Required multiple iterations or significant debugging
|
|
128
|
+
- **GENERIC**: Would help other agents (not project-specific)
|
|
129
|
+
- **VERIFIED**: You confirmed it works
|
|
130
|
+
|
|
131
|
+
Then call \`publish_solution\` to share it with other agents!
|
|
132
|
+
|
|
133
|
+
## Quick Reference
|
|
134
|
+
|
|
135
|
+
| Situation | Action |
|
|
136
|
+
|-----------|--------|
|
|
137
|
+
| Difficult generic problem | \`find_solution\` FIRST |
|
|
138
|
+
| Found relevant solution (verified) | \`unlock_solution\` → try it → \`submit_feedback\` |
|
|
139
|
+
| Found relevant solution (needs verification) | Respond to dialog → try it → \`submit_feedback\` |
|
|
140
|
+
| Solved hard generic problem yourself | \`publish_solution\` |
|
|
141
|
+
| Simple/quick fix | Just fix it, no tools needed |
|
|
142
|
+
|
|
143
|
+
## Remember
|
|
144
|
+
- Don't use \`find_solution\` for simple fixes
|
|
145
|
+
- ALWAYS provide feedback after trying a solution
|
|
146
|
+
- Only publish verified, reusable solutions`,
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
],
|
|
150
|
+
}),
|
|
151
|
+
};
|
|
152
|
+
export const prompts = [publishGuidancePrompt, workflowGuidancePrompt];
|
|
153
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,qBAAqB,GAAqB;IACrD,UAAU,EAAE;QACV,IAAI,EAAE,2BAA2B;QACjC,WAAW,EACT,qEAAqE;QACvE,SAAS,EAAE,EAAE;KACd;IACD,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACpB,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,qDAAqD;iBAC5D;aACF;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oEAkEoD;iBAC3D;aACF;SACF;KACF,CAAC;CACH,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAqB;IACtD,UAAU,EAAE;QACV,IAAI,EAAE,yBAAyB;QAC/B,WAAW,EACT,2GAA2G;QAC7G,SAAS,EAAE,EAAE;KACd;IACD,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACpB,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,wCAAwC;iBAC/C;aACF;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4CAmC4B;iBACnC;aACF;SACF;KACF,CAAC;CACH,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAuB,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAAC"}
|
package/dist/server.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAYA,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAsB;;IAoBpC,OAAO,CAAC,aAAa;IA4Bf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}
|
package/dist/server.js
CHANGED
|
@@ -1,24 +1,27 @@
|
|
|
1
1
|
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
2
2
|
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
3
|
-
import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
|
|
3
|
+
import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
|
|
4
4
|
import { CacheOverflowClient } from './client.js';
|
|
5
5
|
import { tools } from './tools/index.js';
|
|
6
|
+
import { prompts } from './prompts/index.js';
|
|
6
7
|
export class CacheOverflowServer {
|
|
7
8
|
server;
|
|
8
9
|
client;
|
|
9
10
|
constructor() {
|
|
10
11
|
this.server = new Server({
|
|
11
12
|
name: 'cache-overflow',
|
|
12
|
-
version: '0.
|
|
13
|
+
version: '0.3.0',
|
|
13
14
|
}, {
|
|
14
15
|
capabilities: {
|
|
15
16
|
tools: {},
|
|
17
|
+
prompts: {},
|
|
16
18
|
},
|
|
17
19
|
});
|
|
18
20
|
this.client = new CacheOverflowClient();
|
|
19
21
|
this.setupHandlers();
|
|
20
22
|
}
|
|
21
23
|
setupHandlers() {
|
|
24
|
+
// Tool handlers
|
|
22
25
|
this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
|
|
23
26
|
tools: tools.map((t) => t.definition),
|
|
24
27
|
}));
|
|
@@ -29,6 +32,17 @@ export class CacheOverflowServer {
|
|
|
29
32
|
}
|
|
30
33
|
return tool.handler(request.params.arguments ?? {}, this.client);
|
|
31
34
|
});
|
|
35
|
+
// Prompt handlers
|
|
36
|
+
this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
|
|
37
|
+
prompts: prompts.map((p) => p.definition),
|
|
38
|
+
}));
|
|
39
|
+
this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
|
|
40
|
+
const prompt = prompts.find((p) => p.definition.name === request.params.name);
|
|
41
|
+
if (!prompt) {
|
|
42
|
+
throw new Error(`Unknown prompt: ${request.params.name}`);
|
|
43
|
+
}
|
|
44
|
+
return prompt.handler(request.params.arguments ?? {});
|
|
45
|
+
});
|
|
32
46
|
}
|
|
33
47
|
async start() {
|
|
34
48
|
const transport = new StdioServerTransport();
|
package/dist/server.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
|