Skip to content

Commit 0529a23

Browse files
mvalancymvalancy
committed
Add MCP server package configuration
- Package.json with comprehensive test scripts including chaos testing - TypeScript configuration for strict type checking - Vitest configuration for testing infrastructure - ESLint configuration for code quality - README with setup and usage instructions
1 parent c2d2fdc commit 0529a23

5 files changed

Lines changed: 274 additions & 0 deletions

File tree

‎packages/mcp-server/README.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# GraphDone MCP Server
2+
3+
🤖 **Control your GraphDone graph with natural language through Claude Code!**
4+
5+
This MCP (Model Context Protocol) server acts as a bridge between Claude Code and your GraphDone graph database. Instead of clicking through UIs or writing complex queries, just ask Claude to:
6+
7+
- *"Show me all active tasks"*
8+
- *"Create a new epic for mobile development"*
9+
- *"What's blocking the user authentication feature?"*
10+
- *"Add a dependency between task A and task B"*
11+
12+
## What You Get
13+
14+
Transform how you interact with your project management graph:
15+
16+
- 🔍 **Smart Browsing**: Query nodes by type, status, contributor, priority, or search terms
17+
- ➕ **Easy Creation**: Create tasks, epics, bugs, and features through conversation
18+
- ✏️ **Quick Updates**: Modify status, assignments, and properties instantly
19+
- 🔗 **Relationship Management**: Add or remove dependencies and connections
20+
- 🛤️ **Path Analysis**: Find how work items connect and detect circular dependencies
21+
- 📊 **Detailed Insights**: Get comprehensive information about any work item
22+
23+
## Available Tools
24+
25+
### browse_graph
26+
Query the graph structure with various filters:
27+
- `all_nodes`: Get all nodes (with limit)
28+
- `by_type`: Filter by node type
29+
- `by_status`: Filter by node status
30+
- `by_contributor`: Filter by contributor ID
31+
- `by_priority`: Filter by minimum priority threshold
32+
- `dependencies`: Get dependencies and dependents for a specific node
33+
- `search`: Search nodes by title/description
34+
35+
### create_node
36+
Create a new node in the graph with specified properties.
37+
38+
### update_node
39+
Update an existing node's properties.
40+
41+
### delete_node
42+
Delete a node and all its relationships.
43+
44+
### create_edge
45+
Create a relationship between two nodes.
46+
47+
### delete_edge
48+
Delete a specific relationship between two nodes.
49+
50+
### get_node_details
51+
Get comprehensive information about a node including all relationships and contributors.
52+
53+
### find_path
54+
Find the shortest path between two nodes.
55+
56+
### detect_cycles
57+
Detect circular dependencies in the graph.
58+
59+
## Configuration
60+
61+
Set these environment variables:
62+
- `NEO4J_URI`: Neo4j database URI (default: bolt://localhost:7687)
63+
- `NEO4J_USER`: Database username (default: neo4j)
64+
- `NEO4J_PASSWORD`: Database password (default: graphdone_password)
65+
66+
## 🚀 Quick Setup (Recommended)
67+
68+
**One command does it all:**
69+
70+
```bash
71+
./scripts/setup-mcp.sh
72+
```
73+
74+
This friendly setup script will:
75+
- ✅ Check that you have Node.js installed
76+
- 🔨 Build the MCP server automatically
77+
- 🔗 Configure Claude Code to use it
78+
- 📋 Show you exactly what to do next
79+
- 🛡️ Create backups of your settings (just in case)
80+
81+
**Total setup time: Under 2 minutes!**
82+
83+
## ✨ How to Use After Setup
84+
85+
Once configured, just talk to Claude Code naturally:
86+
87+
| What you say | What Claude does |
88+
|-------------|------------------|
89+
| "Show me all tasks in progress" | Uses `browse_graph` to filter by status |
90+
| "Create a bug report for login issues" | Uses `create_node` to add a new bug |
91+
| "What depends on the database migration?" | Uses `browse_graph` to find dependencies |
92+
| "Mark task ABC as completed" | Uses `update_node` to change status |
93+
| "Connect feature X to epic Y" | Uses `create_edge` to add relationship |
94+
95+
**No commands to remember - just describe what you want!**
96+
97+
## 🔧 Manual Setup (If Needed)
98+
99+
If the automatic setup doesn't work, you can configure manually:
100+
101+
**Option 1: Use the Claude CLI**
102+
```bash
103+
claude mcp add graphdone "$(which node)" "$(pwd)/packages/mcp-server/dist/index.js" \
104+
--env "NEO4J_URI=bolt://localhost:7687" \
105+
--env "NEO4J_USER=neo4j" \
106+
--env "NEO4J_PASSWORD=graphdone_password"
107+
```
108+
109+
**Option 2: Edit Claude Code settings file directly**
110+
111+
Find your Claude Code settings file:
112+
- **Linux**: `~/.config/claude-code/config.json`
113+
- **macOS**: `~/Library/Application Support/claude-code/config.json`
114+
- **Windows**: `%APPDATA%/claude-code/config.json`
115+
116+
Add this configuration:
117+
```json
118+
{
119+
"mcpServers": {
120+
"graphdone": {
121+
"command": "node",
122+
"args": ["path/to/packages/mcp-server/dist/index.js"],
123+
"env": {
124+
"NEO4J_URI": "bolt://localhost:7687",
125+
"NEO4J_USER": "neo4j",
126+
"NEO4J_PASSWORD": "graphdone_password"
127+
}
128+
}
129+
}
130+
}
131+
```
132+
133+
## 🚨 Troubleshooting
134+
135+
**MCP server not appearing in Claude Code?**
136+
- Run `claude mcp list` to check if it's registered
137+
- Make sure Claude Code is fully restarted
138+
- Verify the file path in your configuration
139+
140+
**Getting connection errors?**
141+
- Check that Neo4j is running: `docker-compose up -d`
142+
- Test the server health: `curl http://localhost:3128/health`
143+
- Verify your database password is correct
144+
145+
**Setup script failed?**
146+
- Make sure you're in the GraphDone project root directory
147+
- Check that Node.js and npm are installed: `node --version && npm --version`
148+
- Run `npm install` first if dependencies are missing
149+
150+
## Development
151+
152+
```bash
153+
npm run build # Build TypeScript
154+
npm run dev # Development with watch mode
155+
npm run test # Run tests
156+
npm run lint # Lint code
157+
```

‎packages/mcp-server/eslint.config.js‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import globals from 'globals';
2+
import typescript from '@typescript-eslint/eslint-plugin';
3+
import parser from '@typescript-eslint/parser';
4+
5+
export default [
6+
{
7+
files: ['**/*.ts'],
8+
languageOptions: {
9+
globals: globals.node,
10+
parser: parser,
11+
parserOptions: {
12+
ecmaVersion: 2022,
13+
sourceType: 'module',
14+
project: './tsconfig.json',
15+
},
16+
},
17+
plugins: {
18+
'@typescript-eslint': typescript,
19+
},
20+
rules: {
21+
...typescript.configs.recommended.rules,
22+
'@typescript-eslint/no-unused-vars': 'error',
23+
'@typescript-eslint/no-explicit-any': 'warn',
24+
},
25+
},
26+
];

‎packages/mcp-server/package.json‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{
2+
"name": "@graphdone/mcp-server",
3+
"version": "0.2.1-alpha",
4+
"description": "MCP server for GraphDone graph operations",
5+
"main": "dist/index.js",
6+
"type": "module",
7+
"scripts": {
8+
"build": "tsc",
9+
"dev": "echo 'MCP server should be started by Claude Code, not npm run dev. Use npm run dev:mcp to start manually.'",
10+
"dev:start": "tsx watch src/index.ts",
11+
"start": "node dist/index.js",
12+
"test": "vitest --run",
13+
"test:coverage": "vitest run --coverage",
14+
"test:chaos": "vitest --run tests/chaos-testing.test.ts",
15+
"test:chaos:comprehensive": "vitest --run tests/comprehensive-chaos.test.ts",
16+
"test:chaos:real": "vitest --run tests/real-chaos-testing.test.ts",
17+
"test:chaos:multi": "vitest --run tests/multi-perspective-chaos.test.ts",
18+
"chaos": "./scripts/chaos-test.sh",
19+
"lint": "eslint src --ext .ts",
20+
"typecheck": "tsc --noEmit",
21+
"clean": "rm -rf dist coverage",
22+
"ci:full": "npm run lint && npm run typecheck && npm run test && npm run test:chaos:real"
23+
},
24+
"dependencies": {
25+
"@graphdone/core": "*",
26+
"@modelcontextprotocol/sdk": "^0.5.0",
27+
"neo4j-driver": "^5.15.0",
28+
"dotenv": "^16.3.0",
29+
"zod": "^3.22.0"
30+
},
31+
"devDependencies": {
32+
"@types/node": "^20.10.0",
33+
"@typescript-eslint/eslint-plugin": "^8.39.1",
34+
"@typescript-eslint/parser": "^8.39.1",
35+
"@vitest/coverage-v8": "^1.0.0",
36+
"eslint": "^9.33.0",
37+
"globals": "^16.3.0",
38+
"tsx": "^4.6.0",
39+
"typescript": "^5.3.0",
40+
"vitest": "^1.0.0"
41+
},
42+
"files": [
43+
"dist",
44+
"src"
45+
],
46+
"license": "MIT"
47+
}

‎packages/mcp-server/tsconfig.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"compilerOptions": {
3+
"target": "ES2022",
4+
"lib": ["ES2022"],
5+
"module": "ES2022",
6+
"outDir": "./dist",
7+
"rootDir": "./src",
8+
"moduleResolution": "node",
9+
"esModuleInterop": true,
10+
"allowSyntheticDefaultImports": true,
11+
"strict": true,
12+
"skipLibCheck": true,
13+
"forceConsistentCasingInFileNames": true,
14+
"resolveJsonModule": true,
15+
"declaration": true,
16+
"declarationMap": true,
17+
"sourceMap": true,
18+
"noUnusedLocals": true,
19+
"noUnusedParameters": true,
20+
"noImplicitReturns": true,
21+
"noFallthroughCasesInSwitch": true,
22+
"isolatedModules": true,
23+
"incremental": true
24+
},
25+
"include": ["src/**/*"],
26+
"exclude": ["node_modules", "dist", "**/*.test.ts"]
27+
}

‎packages/mcp-server/vitest.config.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
import { defineConfig } from 'vitest/config';
2+
3+
export default defineConfig({
4+
test: {
5+
environment: 'node',
6+
coverage: {
7+
provider: 'v8',
8+
reporter: ['text', 'html'],
9+
exclude: [
10+
'node_modules/',
11+
'dist/',
12+
'**/*.d.ts',
13+
'**/*.config.*',
14+
],
15+
},
16+
},
17+
});

0 commit comments

Comments
 (0)