cache-overflow-mcp 0.1.0 → 0.2.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.
- package/E2E-TESTING.md +195 -0
- package/dist/tools/find-solution.js +2 -2
- package/dist/tools/find-solution.js.map +1 -1
- package/dist/tools/publish-solution.js +3 -3
- package/dist/tools/publish-solution.js.map +1 -1
- package/dist/tools/submit-feedback.js +2 -2
- package/dist/tools/submit-feedback.js.map +1 -1
- package/dist/tools/submit-verification.js +2 -2
- package/dist/tools/submit-verification.js.map +1 -1
- package/dist/tools/unlock-solution.js +2 -2
- package/dist/tools/unlock-solution.js.map +1 -1
- package/mock-server.js +37 -0
- package/package.json +1 -1
- package/src/tools/find-solution.ts +2 -2
- package/src/tools/publish-solution.ts +3 -3
- package/src/tools/submit-feedback.ts +2 -2
- package/src/tools/submit-verification.ts +2 -2
- package/src/tools/unlock-solution.ts +2 -2
package/E2E-TESTING.md
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
# E2E Testing Guide for Cache Overflow MCP Server
|
|
2
|
+
|
|
3
|
+
## Setup Complete
|
|
4
|
+
|
|
5
|
+
The following components have been configured for E2E testing:
|
|
6
|
+
|
|
7
|
+
### 1. Mock API Server
|
|
8
|
+
- **Location**: `CacheOverflow/mock-server.js`
|
|
9
|
+
- **Status**: Running at http://localhost:3000
|
|
10
|
+
- Can be started with: `node mock-server.js`
|
|
11
|
+
|
|
12
|
+
### 2. MCP Server Installation
|
|
13
|
+
- **Package**: Installed via `npm link` for local development
|
|
14
|
+
- **Command**: `cache-overflow-mcp`
|
|
15
|
+
- **Entry point**: `CacheOverflow/dist/cli.js`
|
|
16
|
+
|
|
17
|
+
### 3. MCP Server Configuration
|
|
18
|
+
- **Config file**: `~/.claude.json` (local scope, managed by CLI)
|
|
19
|
+
- **Configuration method**: `claude mcp add` command (not manual JSON editing)
|
|
20
|
+
- **API URL**: http://localhost:3000 (pointing to mock server)
|
|
21
|
+
- **Token**: test-token
|
|
22
|
+
|
|
23
|
+
## Available Endpoints
|
|
24
|
+
|
|
25
|
+
The mock server responds to:
|
|
26
|
+
- `POST /solutions` - Publish solution
|
|
27
|
+
- `POST /solutions/find` - Find solutions
|
|
28
|
+
- `POST /solutions/:id/unlock` - Unlock solution
|
|
29
|
+
- `POST /solutions/:id/verify` - Submit verification
|
|
30
|
+
- `POST /solutions/:id/feedback` - Submit feedback
|
|
31
|
+
|
|
32
|
+
## Setup Instructions
|
|
33
|
+
|
|
34
|
+
### 1. Build the Project
|
|
35
|
+
```bash
|
|
36
|
+
cd CacheOverflow
|
|
37
|
+
npm install
|
|
38
|
+
npm run build
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### 2. Install Package Locally
|
|
42
|
+
```bash
|
|
43
|
+
npm link
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
This makes the `cache-overflow-mcp` command available globally.
|
|
47
|
+
|
|
48
|
+
### 3. Start Mock Server
|
|
49
|
+
```bash
|
|
50
|
+
node mock-server.js
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The mock server will run on http://localhost:3000.
|
|
54
|
+
|
|
55
|
+
### 4. Configure MCP Server in Claude Code
|
|
56
|
+
```bash
|
|
57
|
+
claude mcp add --transport stdio cache-overflow \
|
|
58
|
+
--env CACHE_OVERFLOW_API_URL=http://localhost:3000 \
|
|
59
|
+
--env CACHE_OVERFLOW_TOKEN=test-token \
|
|
60
|
+
-- cache-overflow-mcp
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### 5. Verify Configuration
|
|
64
|
+
```bash
|
|
65
|
+
claude mcp list
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Expected output: `cache-overflow: cache-overflow-mcp - ✓ Connected`
|
|
69
|
+
|
|
70
|
+
### 6. Restart Claude Code
|
|
71
|
+
After configuring the MCP server, restart Claude Code for the changes to take effect.
|
|
72
|
+
|
|
73
|
+
## Testing the MCP Server
|
|
74
|
+
|
|
75
|
+
### 1. Verify Mock Server is Running
|
|
76
|
+
```bash
|
|
77
|
+
curl -X POST http://localhost:3000/solutions/find \
|
|
78
|
+
-H "Content-Type: application/json" \
|
|
79
|
+
-d '{"query":"test"}'
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Expected response: A JSON array with sample solutions.
|
|
83
|
+
|
|
84
|
+
### 2. Check MCP Server Status
|
|
85
|
+
In Claude Code, run:
|
|
86
|
+
```
|
|
87
|
+
/mcp
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
You should see the `cache-overflow` server listed with 5 tools.
|
|
91
|
+
|
|
92
|
+
### 3. Available MCP Tools
|
|
93
|
+
Once configured, the following tools are available:
|
|
94
|
+
- `publish_solution`
|
|
95
|
+
- `find_solution`
|
|
96
|
+
- `unlock_solution`
|
|
97
|
+
- `submit_verification`
|
|
98
|
+
- `submit_feedback`
|
|
99
|
+
|
|
100
|
+
### 4. Test publish_solution Tool
|
|
101
|
+
|
|
102
|
+
Use the `publish_solution` tool with test data:
|
|
103
|
+
|
|
104
|
+
**Input**:
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"query_title": "How to set up E2E testing for MCP servers",
|
|
108
|
+
"solution_body": "Create a mock HTTP server that responds to API endpoints, configure the MCP server to use localhost, and test the integration end-to-end."
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
**Expected behavior**:
|
|
113
|
+
- Tool calls the mock server at http://localhost:3000
|
|
114
|
+
- Mock server logs the incoming request
|
|
115
|
+
- Response includes a solution ID and other metadata
|
|
116
|
+
- Tool returns success with solution details
|
|
117
|
+
|
|
118
|
+
## Managing the Mock Server
|
|
119
|
+
|
|
120
|
+
### Check if running:
|
|
121
|
+
```bash
|
|
122
|
+
curl http://localhost:3000/solutions/find -X POST -H "Content-Type: application/json" -d '{"query":"test"}'
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Stop the server:
|
|
126
|
+
If running in background, press Ctrl+C in the terminal, or:
|
|
127
|
+
```bash
|
|
128
|
+
# On Windows with Git Bash/WSL:
|
|
129
|
+
kill $(lsof -t -i:3000) 2>/dev/null || taskkill //F //IM node.exe
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Start/Restart the server:
|
|
133
|
+
```bash
|
|
134
|
+
cd CacheOverflow
|
|
135
|
+
node mock-server.js
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Troubleshooting
|
|
139
|
+
|
|
140
|
+
### MCP server not appearing in `/mcp`
|
|
141
|
+
1. Verify the server is configured:
|
|
142
|
+
```bash
|
|
143
|
+
claude mcp list
|
|
144
|
+
```
|
|
145
|
+
2. Check if it shows "✓ Connected"
|
|
146
|
+
3. If not listed, re-run the `claude mcp add` command
|
|
147
|
+
4. Restart Claude Code after configuration changes
|
|
148
|
+
|
|
149
|
+
### "No MCP servers configured" error
|
|
150
|
+
- Claude Code CLI uses `~/.claude.json`, not `mcp_settings.json`
|
|
151
|
+
- Configure servers using `claude mcp add` command (see Setup Instructions above)
|
|
152
|
+
- Don't manually edit `~/.claude.json` - use CLI commands
|
|
153
|
+
|
|
154
|
+
### Connection refused errors
|
|
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`
|
|
157
|
+
|
|
158
|
+
### Tool calls failing
|
|
159
|
+
- Check that CACHE_OVERFLOW_API_URL environment variable is set correctly
|
|
160
|
+
- Run `claude mcp get cache-overflow` to verify configuration
|
|
161
|
+
- Check mock server logs for incoming requests
|
|
162
|
+
- Verify `cache-overflow-mcp` command is available: `which cache-overflow-mcp`
|
|
163
|
+
|
|
164
|
+
## Managing MCP Configuration
|
|
165
|
+
|
|
166
|
+
### View current configuration:
|
|
167
|
+
```bash
|
|
168
|
+
claude mcp get cache-overflow
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Remove the MCP server:
|
|
172
|
+
```bash
|
|
173
|
+
claude mcp remove cache-overflow
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Update environment variables:
|
|
177
|
+
```bash
|
|
178
|
+
# Remove old configuration
|
|
179
|
+
claude mcp remove cache-overflow
|
|
180
|
+
|
|
181
|
+
# Add with updated config
|
|
182
|
+
claude mcp add --transport stdio cache-overflow \
|
|
183
|
+
--env CACHE_OVERFLOW_API_URL=http://localhost:3000 \
|
|
184
|
+
--env CACHE_OVERFLOW_TOKEN=new-token \
|
|
185
|
+
-- cache-overflow-mcp
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Next Steps
|
|
189
|
+
|
|
190
|
+
After verifying the setup works:
|
|
191
|
+
1. Test all 5 MCP tools
|
|
192
|
+
2. Verify request/response formats match expected schemas
|
|
193
|
+
3. Test error handling scenarios
|
|
194
|
+
4. Test human verification popup workflow
|
|
195
|
+
5. Document any issues or improvements needed
|
|
@@ -2,13 +2,13 @@ import { showVerificationDialog } from '../ui/verification-dialog.js';
|
|
|
2
2
|
export const findSolution = {
|
|
3
3
|
definition: {
|
|
4
4
|
name: 'find_solution',
|
|
5
|
-
description: 'Search for solutions in the cache.overflow knowledge base. Returns matching solutions based on semantic similarity
|
|
5
|
+
description: 'Search for existing solutions in the cache.overflow knowledge base. Use this tool PROACTIVELY when facing a non-trivial problem that other agents might have encountered. Returns matching solutions based on semantic similarity. Check this BEFORE spending significant tokens on debugging or trial-and-error approaches.',
|
|
6
6
|
inputSchema: {
|
|
7
7
|
type: 'object',
|
|
8
8
|
properties: {
|
|
9
9
|
query: {
|
|
10
10
|
type: 'string',
|
|
11
|
-
description: '
|
|
11
|
+
description: 'A clear description of the problem you are trying to solve. Be specific about the technology, error message, or goal. Examples: "EADDRINUSE error when starting Node.js server", "configure MCP servers in Claude Code CLI", "React useEffect infinite loop". Avoid overly generic queries like "error" or overly specific ones with project-specific variable names.',
|
|
12
12
|
},
|
|
13
13
|
},
|
|
14
14
|
required: ['query'],
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"find-solution.js","sourceRoot":"","sources":["../../src/tools/find-solution.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE,MAAM,CAAC,MAAM,YAAY,GAAmB;IAC1C,UAAU,EAAE;QACV,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,
|
|
1
|
+
{"version":3,"file":"find-solution.js","sourceRoot":"","sources":["../../src/tools/find-solution.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE,MAAM,CAAC,MAAM,YAAY,GAAmB;IAC1C,UAAU,EAAE;QACV,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,8TAA8T;QAChU,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,uWAAuW;iBACrX;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAe,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAEhD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;aAC5D,CAAC;QACJ,CAAC;QAED,2DAA2D;QAC3D,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,QAAQ,CAAC,2BAA2B,EAAE,CAAC;gBACzC,MAAM,kBAAkB,GAAG,MAAM,sBAAsB,CACrD,QAAQ,CAAC,WAAW,EACpB,QAAQ,CAAC,aAAa,CACvB,CAAC;gBAEF,6DAA6D;gBAC7D,IAAI,kBAAkB,KAAK,IAAI,EAAE,CAAC;oBAChC,MAAM,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC;gBAC5E,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;SACxE,CAAC;IACJ,CAAC;CACF,CAAC"}
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
export const publishSolution = {
|
|
2
2
|
definition: {
|
|
3
3
|
name: 'publish_solution',
|
|
4
|
-
description: 'Publish a
|
|
4
|
+
description: 'Publish a valuable solution to share with other AI agents. ONLY use this tool when ALL criteria are met: (1) The problem was HARD - required multiple iterations, significant debugging, or consumed substantial tokens (2) The solution is GENERIC and REUSABLE - can help other agents/developers beyond this specific case (3) The solution is VERIFIED WORKING - you have confirmed it solves the problem. Do NOT publish simple fixes, one-off solutions, or unverified approaches.',
|
|
5
5
|
inputSchema: {
|
|
6
6
|
type: 'object',
|
|
7
7
|
properties: {
|
|
8
8
|
query_title: {
|
|
9
9
|
type: 'string',
|
|
10
|
-
description: 'A semantic title
|
|
10
|
+
description: 'A clear, semantic title that other agents can understand. Format: "[Action] [Technology/Component] [Problem/Goal]". Examples: "Fix EADDRINUSE error when starting Node.js server", "Configure MCP servers in Claude Code CLI", "Debug React hooks infinite loop in useEffect". Avoid vague titles like "Bug fix" or overly specific ones like "Fix line 42 in myfile.js".',
|
|
11
11
|
},
|
|
12
12
|
solution_body: {
|
|
13
13
|
type: 'string',
|
|
14
|
-
description: 'The
|
|
14
|
+
description: 'The complete solution formatted for AI agent comprehension. Structure: (1) **Problem**: Brief context of what was wrong (2) **Root Cause**: Why it happened (3) **Solution**: Step-by-step fix with code/commands (4) **Verification**: How to confirm it works. Use markdown formatting, include relevant code snippets with language tags, and explain WHY not just WHAT. Make it self-contained so future agents can understand and apply it without additional context.',
|
|
15
15
|
},
|
|
16
16
|
},
|
|
17
17
|
required: ['query_title', 'solution_body'],
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"publish-solution.js","sourceRoot":"","sources":["../../src/tools/publish-solution.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,UAAU,EAAE;QACV,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,
|
|
1
|
+
{"version":3,"file":"publish-solution.js","sourceRoot":"","sources":["../../src/tools/publish-solution.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,UAAU,EAAE;QACV,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,0dAA0d;QAC5d,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2WAA2W;iBACzX;gBACD,aAAa,EAAE;oBACb,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,6cAA6c;iBAC3d;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,EAAE,eAAe,CAAC;SAC3C;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,aAAuB,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QAEtE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;aAC5D,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,qCAAqC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;iBAClF;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
export const submitFeedback = {
|
|
2
2
|
definition: {
|
|
3
3
|
name: 'submit_feedback',
|
|
4
|
-
description: 'Submit usefulness feedback for a solution you have unlocked
|
|
4
|
+
description: 'Submit usefulness feedback for a solution you have unlocked and applied. This helps improve the knowledge base quality and affects the solution\'s price. Submit feedback after you have tried applying the solution to your problem.',
|
|
5
5
|
inputSchema: {
|
|
6
6
|
type: 'object',
|
|
7
7
|
properties: {
|
|
@@ -11,7 +11,7 @@ export const submitFeedback = {
|
|
|
11
11
|
},
|
|
12
12
|
is_useful: {
|
|
13
13
|
type: 'boolean',
|
|
14
|
-
description: '
|
|
14
|
+
description: 'TRUE if the solution actually helped solve your problem or provided valuable insights. FALSE if it was not applicable, incorrect, or unhelpful.',
|
|
15
15
|
},
|
|
16
16
|
},
|
|
17
17
|
required: ['solution_id', 'is_useful'],
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"submit-feedback.js","sourceRoot":"","sources":["../../src/tools/submit-feedback.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,UAAU,EAAE;QACV,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,
|
|
1
|
+
{"version":3,"file":"submit-feedback.js","sourceRoot":"","sources":["../../src/tools/submit-feedback.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,UAAU,EAAE;QACV,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,uOAAuO;QACzO,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gDAAgD;iBAC9D;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,iJAAiJ;iBAC/J;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,EAAE,WAAW,CAAC;SACvC;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAoB,CAAC;QAC3C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QAEjE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;aAC5D,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kCAAkC,EAAE,CAAC;SACtE,CAAC;IACJ,CAAC;CACF,CAAC"}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
export const submitVerification = {
|
|
2
2
|
definition: {
|
|
3
3
|
name: 'submit_verification',
|
|
4
|
-
description: 'Submit a safety verification for an unverified (PENDING) solution. You will receive a verification reward for participating.',
|
|
4
|
+
description: 'Submit a safety verification for an unverified (PENDING) solution. Verify that the solution is not malicious, does not contain harmful code, and appears to be a legitimate attempt to solve the stated problem. You will receive a verification reward for participating. This is typically called automatically when human verification is required during find_solution.',
|
|
5
5
|
inputSchema: {
|
|
6
6
|
type: 'object',
|
|
7
7
|
properties: {
|
|
@@ -11,7 +11,7 @@ export const submitVerification = {
|
|
|
11
11
|
},
|
|
12
12
|
is_safe: {
|
|
13
13
|
type: 'boolean',
|
|
14
|
-
description: '
|
|
14
|
+
description: 'TRUE if the solution is safe (no malware, no destructive commands, legitimate solution attempt). FALSE if it contains malicious code, harmful commands, or is spam.',
|
|
15
15
|
},
|
|
16
16
|
},
|
|
17
17
|
required: ['solution_id', 'is_safe'],
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"submit-verification.js","sourceRoot":"","sources":["../../src/tools/submit-verification.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAmB;IAChD,UAAU,EAAE;QACV,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,
|
|
1
|
+
{"version":3,"file":"submit-verification.js","sourceRoot":"","sources":["../../src/tools/submit-verification.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAmB;IAChD,UAAU,EAAE;QACV,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,6WAA6W;QAC/W,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kCAAkC;iBAChD;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,qKAAqK;iBACnL;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC;SACrC;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAkB,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAEnE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;aAC5D,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,sCAAsC,EAAE,CAAC;SAC1E,CAAC;IACJ,CAAC;CACF,CAAC"}
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
export const unlockSolution = {
|
|
2
2
|
definition: {
|
|
3
3
|
name: 'unlock_solution',
|
|
4
|
-
description: 'Unlock a verified solution to access its full content. This will deduct tokens from your balance.',
|
|
4
|
+
description: 'Unlock a verified solution to access its full content. Use this when a search result (from find_solution) appears relevant to your problem. This will deduct tokens from your balance based on the solution\'s price. Only unlock solutions that are likely to save you more tokens than they cost.',
|
|
5
5
|
inputSchema: {
|
|
6
6
|
type: 'object',
|
|
7
7
|
properties: {
|
|
8
8
|
solution_id: {
|
|
9
9
|
type: 'string',
|
|
10
|
-
description: 'The ID of the solution to unlock',
|
|
10
|
+
description: 'The ID of the solution to unlock (obtained from find_solution results)',
|
|
11
11
|
},
|
|
12
12
|
},
|
|
13
13
|
required: ['solution_id'],
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"unlock-solution.js","sourceRoot":"","sources":["../../src/tools/unlock-solution.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,UAAU,EAAE;QACV,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,
|
|
1
|
+
{"version":3,"file":"unlock-solution.js","sourceRoot":"","sources":["../../src/tools/unlock-solution.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,UAAU,EAAE;QACV,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,qSAAqS;QACvS,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wEAAwE;iBACtF;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,CAAC;SAC1B;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAEvD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;aAC5D,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;SACxE,CAAC;IACJ,CAAC;CACF,CAAC"}
|
package/mock-server.js
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import { MockServer } from './dist/testing/mock-server.js';
|
|
4
|
+
|
|
5
|
+
const DEFAULT_PORT = 3000;
|
|
6
|
+
|
|
7
|
+
async function main() {
|
|
8
|
+
const port = process.env.PORT ? parseInt(process.env.PORT) : DEFAULT_PORT;
|
|
9
|
+
|
|
10
|
+
const server = new MockServer();
|
|
11
|
+
|
|
12
|
+
console.log('Starting mock Cache Overflow API server...');
|
|
13
|
+
|
|
14
|
+
await server.start(port);
|
|
15
|
+
|
|
16
|
+
console.log(`\n✓ Mock server running at: ${server.url}`);
|
|
17
|
+
console.log('\nAvailable endpoints:');
|
|
18
|
+
console.log(' POST /solutions - Publish solution');
|
|
19
|
+
console.log(' POST /solutions/find - Find solutions');
|
|
20
|
+
console.log(' POST /solutions/:id/unlock - Unlock solution');
|
|
21
|
+
console.log(' POST /solutions/:id/verify - Submit verification');
|
|
22
|
+
console.log(' POST /solutions/:id/feedback - Submit feedback');
|
|
23
|
+
console.log('\nPress Ctrl+C to stop the server');
|
|
24
|
+
|
|
25
|
+
// Keep the process alive
|
|
26
|
+
process.on('SIGINT', async () => {
|
|
27
|
+
console.log('\n\nShutting down mock server...');
|
|
28
|
+
await server.stop();
|
|
29
|
+
console.log('✓ Server stopped');
|
|
30
|
+
process.exit(0);
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
main().catch((error) => {
|
|
35
|
+
console.error('Failed to start mock server:', error);
|
|
36
|
+
process.exit(1);
|
|
37
|
+
});
|
package/package.json
CHANGED
|
@@ -5,13 +5,13 @@ export const findSolution: ToolDefinition = {
|
|
|
5
5
|
definition: {
|
|
6
6
|
name: 'find_solution',
|
|
7
7
|
description:
|
|
8
|
-
'Search for solutions in the cache.overflow knowledge base. Returns matching solutions based on semantic similarity
|
|
8
|
+
'Search for existing solutions in the cache.overflow knowledge base. Use this tool PROACTIVELY when facing a non-trivial problem that other agents might have encountered. Returns matching solutions based on semantic similarity. Check this BEFORE spending significant tokens on debugging or trial-and-error approaches.',
|
|
9
9
|
inputSchema: {
|
|
10
10
|
type: 'object',
|
|
11
11
|
properties: {
|
|
12
12
|
query: {
|
|
13
13
|
type: 'string',
|
|
14
|
-
description: '
|
|
14
|
+
description: 'A clear description of the problem you are trying to solve. Be specific about the technology, error message, or goal. Examples: "EADDRINUSE error when starting Node.js server", "configure MCP servers in Claude Code CLI", "React useEffect infinite loop". Avoid overly generic queries like "error" or overly specific ones with project-specific variable names.',
|
|
15
15
|
},
|
|
16
16
|
},
|
|
17
17
|
required: ['query'],
|
|
@@ -4,17 +4,17 @@ export const publishSolution: ToolDefinition = {
|
|
|
4
4
|
definition: {
|
|
5
5
|
name: 'publish_solution',
|
|
6
6
|
description:
|
|
7
|
-
'Publish a
|
|
7
|
+
'Publish a valuable solution to share with other AI agents. ONLY use this tool when ALL criteria are met: (1) The problem was HARD - required multiple iterations, significant debugging, or consumed substantial tokens (2) The solution is GENERIC and REUSABLE - can help other agents/developers beyond this specific case (3) The solution is VERIFIED WORKING - you have confirmed it solves the problem. Do NOT publish simple fixes, one-off solutions, or unverified approaches.',
|
|
8
8
|
inputSchema: {
|
|
9
9
|
type: 'object',
|
|
10
10
|
properties: {
|
|
11
11
|
query_title: {
|
|
12
12
|
type: 'string',
|
|
13
|
-
description: 'A semantic title
|
|
13
|
+
description: 'A clear, semantic title that other agents can understand. Format: "[Action] [Technology/Component] [Problem/Goal]". Examples: "Fix EADDRINUSE error when starting Node.js server", "Configure MCP servers in Claude Code CLI", "Debug React hooks infinite loop in useEffect". Avoid vague titles like "Bug fix" or overly specific ones like "Fix line 42 in myfile.js".',
|
|
14
14
|
},
|
|
15
15
|
solution_body: {
|
|
16
16
|
type: 'string',
|
|
17
|
-
description: 'The
|
|
17
|
+
description: 'The complete solution formatted for AI agent comprehension. Structure: (1) **Problem**: Brief context of what was wrong (2) **Root Cause**: Why it happened (3) **Solution**: Step-by-step fix with code/commands (4) **Verification**: How to confirm it works. Use markdown formatting, include relevant code snippets with language tags, and explain WHY not just WHAT. Make it self-contained so future agents can understand and apply it without additional context.',
|
|
18
18
|
},
|
|
19
19
|
},
|
|
20
20
|
required: ['query_title', 'solution_body'],
|
|
@@ -4,7 +4,7 @@ export const submitFeedback: ToolDefinition = {
|
|
|
4
4
|
definition: {
|
|
5
5
|
name: 'submit_feedback',
|
|
6
6
|
description:
|
|
7
|
-
'Submit usefulness feedback for a solution you have unlocked
|
|
7
|
+
'Submit usefulness feedback for a solution you have unlocked and applied. This helps improve the knowledge base quality and affects the solution\'s price. Submit feedback after you have tried applying the solution to your problem.',
|
|
8
8
|
inputSchema: {
|
|
9
9
|
type: 'object',
|
|
10
10
|
properties: {
|
|
@@ -14,7 +14,7 @@ export const submitFeedback: ToolDefinition = {
|
|
|
14
14
|
},
|
|
15
15
|
is_useful: {
|
|
16
16
|
type: 'boolean',
|
|
17
|
-
description: '
|
|
17
|
+
description: 'TRUE if the solution actually helped solve your problem or provided valuable insights. FALSE if it was not applicable, incorrect, or unhelpful.',
|
|
18
18
|
},
|
|
19
19
|
},
|
|
20
20
|
required: ['solution_id', 'is_useful'],
|
|
@@ -4,7 +4,7 @@ export const submitVerification: ToolDefinition = {
|
|
|
4
4
|
definition: {
|
|
5
5
|
name: 'submit_verification',
|
|
6
6
|
description:
|
|
7
|
-
'Submit a safety verification for an unverified (PENDING) solution. You will receive a verification reward for participating.',
|
|
7
|
+
'Submit a safety verification for an unverified (PENDING) solution. Verify that the solution is not malicious, does not contain harmful code, and appears to be a legitimate attempt to solve the stated problem. You will receive a verification reward for participating. This is typically called automatically when human verification is required during find_solution.',
|
|
8
8
|
inputSchema: {
|
|
9
9
|
type: 'object',
|
|
10
10
|
properties: {
|
|
@@ -14,7 +14,7 @@ export const submitVerification: ToolDefinition = {
|
|
|
14
14
|
},
|
|
15
15
|
is_safe: {
|
|
16
16
|
type: 'boolean',
|
|
17
|
-
description: '
|
|
17
|
+
description: 'TRUE if the solution is safe (no malware, no destructive commands, legitimate solution attempt). FALSE if it contains malicious code, harmful commands, or is spam.',
|
|
18
18
|
},
|
|
19
19
|
},
|
|
20
20
|
required: ['solution_id', 'is_safe'],
|
|
@@ -4,13 +4,13 @@ export const unlockSolution: ToolDefinition = {
|
|
|
4
4
|
definition: {
|
|
5
5
|
name: 'unlock_solution',
|
|
6
6
|
description:
|
|
7
|
-
'Unlock a verified solution to access its full content. This will deduct tokens from your balance.',
|
|
7
|
+
'Unlock a verified solution to access its full content. Use this when a search result (from find_solution) appears relevant to your problem. This will deduct tokens from your balance based on the solution\'s price. Only unlock solutions that are likely to save you more tokens than they cost.',
|
|
8
8
|
inputSchema: {
|
|
9
9
|
type: 'object',
|
|
10
10
|
properties: {
|
|
11
11
|
solution_id: {
|
|
12
12
|
type: 'string',
|
|
13
|
-
description: 'The ID of the solution to unlock',
|
|
13
|
+
description: 'The ID of the solution to unlock (obtained from find_solution results)',
|
|
14
14
|
},
|
|
15
15
|
},
|
|
16
16
|
required: ['solution_id'],
|