Skip to content

Commit 3df26b6

Browse files
DevMayurMayur Kakade
andauthored
Add SimpleCheckList MCP Server - Advanced Task & Project Management (github#262)
* Add SimpleCheckList MCP Server - Advanced Task & Project Management - Comprehensive hierarchical project management (Projects → Groups → Task Lists → Tasks → Subtasks) - 20 comprehensive tools for complete CRUD operations - 5 resource endpoints for real-time data access - 4 AI-powered prompts for intelligent planning and analysis - Enterprise-grade security with comprehensive audit certification - Production-ready Docker image globally available at mayurkakade/mcp-server - Professional icon and complete documentation - Category: productivity - perfect for Claude Desktop integration - MIT licensed and community-friendly Features: ✅ Hierarchical organization (5 levels deep) ✅ AI-powered project planning assistance ✅ Real-time analytics and progress tracking ✅ Priority management and due date tracking ✅ Rich metadata support for tasks ✅ Multi-deployment support (local, Docker, cloud) ✅ Comprehensive security implementation ✅ Extensive documentation and examples Repository: https://github.com/DevMayur/SimpleCheckList Docker Hub: https://hub.docker.com/r/mayurkakade/mcp-server License: MIT * Add tools.json to fix Docker Desktop tool listing - Define all 20 MCP tools to prevent build failures - Enables proper tool display in Docker Desktop MCP Toolkit - Includes comprehensive tool descriptions and arguments - Fixes '0 tools' issue in Docker Desktop interface * Update SimpleCheckList MCP Server to v1.0.1 with Docker stability improvements - Fixed Docker container exit issue with default backend mode - Enhanced server.yaml with comprehensive description and Docker optimizations - Added comprehensive DOCKER-USAGE-INSTRUCTIONS.txt deployment guide - Created detailed README.md with v1.0.1 improvements and troubleshooting - Added REGISTRY-UPDATE-MESSAGE.txt for PR submission - Improved container lifecycle management and health monitoring - Added production deployment examples (Docker Compose, Kubernetes) - Enhanced user experience for Docker Desktop integration This update significantly improves Docker deployment reliability and user experience. --------- Co-authored-by: Mayur Kakade <[email protected]>
1 parent 775a02b commit 3df26b6

File tree

5 files changed

+821
-0
lines changed

5 files changed

+821
-0
lines changed
Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
SIMPLECHECKLIST MCP SERVER - DOCKER DEPLOYMENT GUIDE
2+
=====================================================
3+
4+
🚀 QUICK START
5+
===============
6+
7+
The SimpleCheckList MCP Server v1.0.1 provides stable Docker deployment with improved container lifecycle management.
8+
9+
BASIC DEPLOYMENT:
10+
docker run -d -p 8355:8355 mayurkakade/mcp-server:latest
11+
12+
The container will start in 'backend' mode by default, providing a stable HTTP API for MCP communication.
13+
14+
📋 DEPLOYMENT MODES
15+
===================
16+
17+
The server supports three deployment modes:
18+
19+
1. BACKEND MODE (Default - Recommended for Docker):
20+
docker run -d -p 8355:8355 mayurkakade/mcp-server:latest
21+
22+
- Runs HTTP API server on port 8355
23+
- Stable container lifecycle
24+
- No immediate exit issues
25+
- Perfect for Docker deployment
26+
- Health check endpoint: http://localhost:8355/api/health
27+
28+
2. MCP MODE (For direct MCP client connections):
29+
docker run -i mayurkakade/mcp-server:latest --mode=mcp
30+
31+
- Uses STDIO transport for MCP protocol
32+
- For direct integration with MCP clients
33+
- Interactive mode required (-i flag)
34+
35+
3. BOTH MODE (HTTP API + MCP server):
36+
docker run -d -p 8355:8355 mayurkakade/mcp-server:latest --mode=both
37+
38+
- Runs both HTTP API and MCP server
39+
- More resource intensive
40+
- Use only if you need both interfaces
41+
42+
🔧 CONFIGURATION OPTIONS
43+
========================
44+
45+
ENVIRONMENT VARIABLES:
46+
- MODE: Set deployment mode (backend|mcp|both) - default: backend
47+
- PORT: HTTP API port - default: 8355
48+
- DB_PATH: SQLite database path - default: /app/data/tasks.db
49+
- LOG_LEVEL: Logging level (debug|info|warn|error) - default: info
50+
51+
EXAMPLE WITH ENVIRONMENT VARIABLES:
52+
docker run -d \
53+
-p 8355:8355 \
54+
-e MODE=backend \
55+
-e PORT=8355 \
56+
-e LOG_LEVEL=info \
57+
mayurkakade/mcp-server:latest
58+
59+
PERSISTENT DATA STORAGE:
60+
docker run -d \
61+
-p 8355:8355 \
62+
-v /host/path/to/data:/app/data \
63+
mayurkakade/mcp-server:latest
64+
65+
This mounts a host directory to persist your SQLite database and task data.
66+
67+
🏥 HEALTH CHECKS & MONITORING
68+
=============================
69+
70+
HEALTH CHECK ENDPOINT:
71+
curl http://localhost:8355/api/health
72+
73+
Expected Response:
74+
{
75+
"status": "OK",
76+
"timestamp": "2025-09-17T12:00:00Z",
77+
"version": "v1.0.1",
78+
"mode": "backend"
79+
}
80+
81+
CONTAINER STATUS:
82+
docker ps --filter "ancestor=mayurkakade/mcp-server:latest"
83+
84+
CONTAINER LOGS:
85+
docker logs <container-id>
86+
87+
Expected startup messages:
88+
- "Starting SimpleCheckList MCP Server v1.0.1"
89+
- "Mode: backend"
90+
- "HTTP API server starting on port 8355"
91+
- "Server ready and accepting connections"
92+
93+
📊 API ENDPOINTS
94+
================
95+
96+
Once running, the HTTP API provides these endpoints:
97+
98+
HEALTH & STATUS:
99+
- GET /api/health - Health check
100+
- GET /api/version - Version information
101+
102+
PROJECT MANAGEMENT:
103+
- GET /api/projects - List all projects
104+
- POST /api/projects - Create new project
105+
- GET /api/projects/{id} - Get specific project
106+
- PUT /api/projects/{id} - Update project
107+
- DELETE /api/projects/{id} - Delete project
108+
109+
TASK MANAGEMENT:
110+
- GET /api/projects/{id}/groups - List project groups
111+
- POST /api/groups - Create new group
112+
- GET /api/groups/{id}/task-lists - List task lists
113+
- POST /api/task-lists - Create task list
114+
- GET /api/task-lists/{id}/tasks - List tasks
115+
- POST /api/tasks - Create task
116+
- PUT /api/tasks/{id} - Update task
117+
- DELETE /api/tasks/{id} - Delete task
118+
119+
🔍 TROUBLESHOOTING
120+
==================
121+
122+
CONTAINER EXITS IMMEDIATELY:
123+
- This was fixed in v1.0.1
124+
- Ensure you're using the latest image: mayurkakade/mcp-server:latest
125+
- Check mode configuration (default 'backend' should work)
126+
127+
CANNOT CONNECT TO API:
128+
- Verify port mapping: -p 8355:8355
129+
- Check if container is running: docker ps
130+
- Test health endpoint: curl http://localhost:8355/api/health
131+
132+
PERMISSION ISSUES:
133+
- Ensure data volume has correct permissions
134+
- Use docker user mapping if needed: --user $(id -u):$(id -g)
135+
136+
DATABASE ISSUES:
137+
- Check data volume mounting
138+
- Verify SQLite file permissions
139+
- Review container logs for database errors
140+
141+
CONNECTION REFUSED:
142+
- Container may still be starting (wait 5-10 seconds)
143+
- Check if port is already in use: netstat -tulpn | grep 8355
144+
- Verify firewall settings
145+
146+
🎯 MCP CLIENT INTEGRATION
147+
=========================
148+
149+
FOR CLAUDE DESKTOP:
150+
Configure in your Claude Desktop settings:
151+
152+
{
153+
"mcpServers": {
154+
"simplechecklist": {
155+
"command": "docker",
156+
"args": [
157+
"run", "-i", "--rm",
158+
"mayurkakade/mcp-server:latest",
159+
"--mode=mcp"
160+
]
161+
}
162+
}
163+
}
164+
165+
FOR HTTP-BASED MCP CLIENTS:
166+
Point your MCP client to: http://localhost:8355/mcp
167+
168+
🚀 PRODUCTION DEPLOYMENT
169+
========================
170+
171+
DOCKER COMPOSE EXAMPLE:
172+
version: '3.8'
173+
services:
174+
simplechecklist:
175+
image: mayurkakade/mcp-server:latest
176+
ports:
177+
- "8355:8355"
178+
volumes:
179+
- ./data:/app/data
180+
environment:
181+
- MODE=backend
182+
- LOG_LEVEL=info
183+
restart: unless-stopped
184+
healthcheck:
185+
test: ["CMD", "curl", "-f", "http://localhost:8355/api/health"]
186+
interval: 30s
187+
timeout: 10s
188+
retries: 3
189+
190+
KUBERNETES DEPLOYMENT:
191+
apiVersion: apps/v1
192+
kind: Deployment
193+
metadata:
194+
name: simplechecklist-mcp
195+
spec:
196+
replicas: 1
197+
selector:
198+
matchLabels:
199+
app: simplechecklist-mcp
200+
template:
201+
metadata:
202+
labels:
203+
app: simplechecklist-mcp
204+
spec:
205+
containers:
206+
- name: simplechecklist
207+
image: mayurkakade/mcp-server:latest
208+
ports:
209+
- containerPort: 8355
210+
env:
211+
- name: MODE
212+
value: "backend"
213+
volumeMounts:
214+
- name: data-storage
215+
mountPath: /app/data
216+
livenessProbe:
217+
httpGet:
218+
path: /api/health
219+
port: 8355
220+
initialDelaySeconds: 10
221+
periodSeconds: 30
222+
volumes:
223+
- name: data-storage
224+
persistentVolumeClaim:
225+
claimName: simplechecklist-data
226+
227+
📈 VERSION HISTORY
228+
==================
229+
230+
v1.0.1 (Latest):
231+
- Fixed Docker container exit issue
232+
- Changed default mode to 'backend' for stability
233+
- Improved startup messaging
234+
- Enhanced error handling
235+
- Better container lifecycle management
236+
237+
v1.0.0:
238+
- Initial Docker release
239+
- Basic MCP server functionality
240+
- SQLite database integration
241+
242+
🤝 SUPPORT
243+
==========
244+
245+
- GitHub Issues: https://github.com/DevMayur/SimpleCheckList/issues
246+
- Docker Hub: https://hub.docker.com/r/mayurkakade/mcp-server
247+
- Documentation: https://github.com/DevMayur/SimpleCheckList#readme
248+
249+
For Docker-specific issues, please include:
250+
- Docker version: docker --version
251+
- Container logs: docker logs <container-id>
252+
- Host system information
253+
- Deployment configuration used
254+
255+
🎉 SUCCESS INDICATORS
256+
=====================
257+
258+
Your deployment is successful when you see:
259+
✅ Container stays running (doesn't exit immediately)
260+
✅ Health check returns HTTP 200
261+
✅ API endpoints respond correctly
262+
✅ MCP client can connect and communicate
263+
✅ Data persists across container restarts
264+
265+
The v1.0.1 Docker stability improvements ensure a reliable deployment experience!

0 commit comments

Comments
 (0)