Skip to content

Commit a213cfd

Browse files
spranabspranab
committed
Add manifest.json and update README for Anthropic directory submission
- Add MCPB manifest.json (v0.3) with all 22 tools, user_config, compatibility - Update README with configuration section, usage examples, privacy policy - Bump to v1.2.0
1 parent aff5c13 commit a213cfd

3 files changed

Lines changed: 220 additions & 43 deletions

File tree

‎README.md‎

Lines changed: 137 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ A Jira-like project tracker MCP server for AI agents. SQLite-backed, per-project
1212
- **Dashboard**: One tool call gives full project overview (stats, blocked tasks, recent changes)
1313
- **Notes system**: Decisions, context, meeting notes, blockers — all searchable
1414
- **Batch operations**: Create multiple subtasks or update multiple tasks in one call
15-
- **22 focused tools**: Reduced from typical 38+ by combining related operations
15+
- **22 focused tools**: With MCP safety annotations on every tool
16+
- **Cross-platform**: Works on macOS, Windows, and Linux
1617

1718
## Quick Start
1819

@@ -59,64 +60,147 @@ npm install -g saga-mcp
5960
DB_PATH=./my-project/.tracker.db saga-mcp
6061
```
6162

63+
## Configuration
64+
65+
saga-mcp requires a single environment variable:
66+
67+
| Variable | Required | Description |
68+
|----------|----------|-------------|
69+
| `DB_PATH` | Yes | Absolute path to the `.tracker.db` SQLite file. The file and schema are auto-created on first use. |
70+
71+
No API keys, no accounts, no external services. Everything is stored locally in the SQLite file you specify.
72+
6273
## Tools
6374

6475
### Getting Started
6576

66-
| Tool | Description |
67-
|------|-------------|
68-
| `tracker_init` | Initialize tracker and create first project |
69-
| `tracker_dashboard` | Full project overview — **call this first when resuming work** |
77+
| Tool | Description | Annotations |
78+
|------|-------------|-------------|
79+
| `tracker_init` | Initialize tracker and create first project | `readOnly: false`, `idempotent: true` |
80+
| `tracker_dashboard` | Full project overview — **call this first when resuming work** | `readOnly: true` |
7081

7182
### Projects
7283

73-
| Tool | Description |
74-
|------|-------------|
75-
| `project_create` | Create a new project |
76-
| `project_list` | List projects with completion stats |
77-
| `project_update` | Update project (archive to soft-delete) |
84+
| Tool | Description | Annotations |
85+
|------|-------------|-------------|
86+
| `project_create` | Create a new project | `readOnly: false` |
87+
| `project_list` | List projects with completion stats | `readOnly: true` |
88+
| `project_update` | Update project (archive to soft-delete) | `readOnly: false`, `idempotent: true` |
7889

7990
### Epics
8091

81-
| Tool | Description |
82-
|------|-------------|
83-
| `epic_create` | Create an epic within a project |
84-
| `epic_list` | List epics with task counts |
85-
| `epic_update` | Update an epic |
92+
| Tool | Description | Annotations |
93+
|------|-------------|-------------|
94+
| `epic_create` | Create an epic within a project | `readOnly: false` |
95+
| `epic_list` | List epics with task counts | `readOnly: true` |
96+
| `epic_update` | Update an epic | `readOnly: false`, `idempotent: true` |
8697

8798
### Tasks
8899

89-
| Tool | Description |
90-
|------|-------------|
91-
| `task_create` | Create a task within an epic |
92-
| `task_list` | List/filter tasks (by epic, status, priority, assignee, tag) |
93-
| `task_get` | Get task with subtasks and related notes |
94-
| `task_update` | Update task (status changes auto-logged) |
95-
| `task_batch_update` | Update multiple tasks at once |
100+
| Tool | Description | Annotations |
101+
|------|-------------|-------------|
102+
| `task_create` | Create a task within an epic | `readOnly: false` |
103+
| `task_list` | List/filter tasks (by epic, status, priority, assignee, tag) | `readOnly: true` |
104+
| `task_get` | Get task with subtasks and related notes | `readOnly: true` |
105+
| `task_update` | Update task (status changes auto-logged) | `readOnly: false`, `idempotent: true` |
106+
| `task_batch_update` | Update multiple tasks at once | `readOnly: false`, `idempotent: true` |
96107

97108
### Subtasks
98109

99-
| Tool | Description |
100-
|------|-------------|
101-
| `subtask_create` | Create subtask(s) — supports batch |
102-
| `subtask_update` | Update subtask title/status |
103-
| `subtask_delete` | Delete subtask(s) — supports batch |
110+
| Tool | Description | Annotations |
111+
|------|-------------|-------------|
112+
| `subtask_create` | Create subtask(s) — supports batch | `readOnly: false` |
113+
| `subtask_update` | Update subtask title/status | `readOnly: false`, `idempotent: true` |
114+
| `subtask_delete` | Delete subtask(s) — supports batch | `destructive: true`, `idempotent: true` |
104115

105116
### Notes
106117

107-
| Tool | Description |
108-
|------|-------------|
109-
| `note_save` | Create or update a note (upsert) |
110-
| `note_list` | List notes with filters |
111-
| `note_search` | Full-text search across notes |
112-
| `note_delete` | Delete a note |
118+
| Tool | Description | Annotations |
119+
|------|-------------|-------------|
120+
| `note_save` | Create or update a note (upsert) | `readOnly: false` |
121+
| `note_list` | List notes with filters | `readOnly: true` |
122+
| `note_search` | Full-text search across notes | `readOnly: true` |
123+
| `note_delete` | Delete a note | `destructive: true`, `idempotent: true` |
113124

114125
### Intelligence
115126

116-
| Tool | Description |
117-
|------|-------------|
118-
| `tracker_search` | Cross-entity search (projects, epics, tasks, notes) |
119-
| `activity_log` | View change history with filters |
127+
| Tool | Description | Annotations |
128+
|------|-------------|-------------|
129+
| `tracker_search` | Cross-entity search (projects, epics, tasks, notes) | `readOnly: true` |
130+
| `activity_log` | View change history with filters | `readOnly: true` |
131+
132+
## Usage Examples
133+
134+
### Example 1: Starting a new project
135+
136+
**User prompt:** "Set up tracking for my new e-commerce API project"
137+
138+
**Tool calls:**
139+
```
140+
tracker_init({ project_name: "E-Commerce API", project_description: "REST API for online store" })
141+
epic_create({ project_id: 1, name: "Authentication", priority: "high" })
142+
epic_create({ project_id: 1, name: "Product Catalog", priority: "medium" })
143+
task_create({ epic_id: 1, title: "Implement JWT auth", priority: "high" })
144+
task_create({ epic_id: 1, title: "Add OAuth2 Google login", priority: "medium" })
145+
subtask_create({ task_id: 1, titles: ["Set up JWT library", "Create login endpoint", "Create refresh endpoint", "Add middleware"] })
146+
```
147+
148+
**Expected output:** Project created with ID 1, two epics, two tasks, and four subtasks. Activity log records all creations.
149+
150+
### Example 2: Resuming work on an existing project
151+
152+
**User prompt:** "What's the current status of my project? What should I work on next?"
153+
154+
**Tool calls:**
155+
```
156+
tracker_dashboard({})
157+
```
158+
159+
**Expected output:**
160+
```json
161+
{
162+
"project": { "id": 1, "name": "E-Commerce API", "status": "active" },
163+
"stats": {
164+
"total_epics": 2,
165+
"total_tasks": 5,
166+
"tasks_done": 2,
167+
"tasks_in_progress": 1,
168+
"tasks_blocked": 1,
169+
"tasks_todo": 1,
170+
"completion_pct": 40.0
171+
},
172+
"epics": [
173+
{ "name": "Authentication", "task_count": 3, "done_count": 2, "completion_pct": 66.7 },
174+
{ "name": "Product Catalog", "task_count": 2, "done_count": 0, "completion_pct": 0 }
175+
],
176+
"blocked_tasks": [
177+
{ "id": 4, "title": "Add rate limiting", "epic_name": "Authentication" }
178+
],
179+
"recent_activity": [...],
180+
"recent_notes": [...]
181+
}
182+
```
183+
184+
The dashboard immediately shows: 40% done, 1 blocked task in Auth, Product Catalog hasn't started. The LLM can now prioritize unblocking the rate limiting task or starting on the catalog.
185+
186+
### Example 3: Recording a decision and marking tasks done
187+
188+
**User prompt:** "We decided to use Redis for caching. Mark the caching research tasks as done."
189+
190+
**Tool calls:**
191+
```
192+
note_save({
193+
title: "Decision: Use Redis for caching",
194+
content: "After evaluating Redis vs Memcached vs in-memory, decided on Redis.\n\nReasons:\n- Built-in persistence\n- Pub/sub for cache invalidation\n- Better data structure support\n\nTrade-offs: Extra infrastructure, but managed Redis on AWS is acceptable.",
195+
note_type: "decision",
196+
related_entity_type: "epic",
197+
related_entity_id: 3,
198+
tags: ["caching", "infrastructure"]
199+
})
200+
task_batch_update({ ids: [8, 9], status: "done" })
201+
```
202+
203+
**Expected output:** Decision note created with ID, linked to the epic. Tasks 8 and 9 marked as done. Activity log records both the note creation and the status changes with "status: todo -> done" entries.
120204

121205
## How It Works
122206

@@ -163,11 +247,18 @@ Every create, update, and delete is automatically recorded:
163247
}
164248
```
165249

166-
## Environment Variables
250+
## Privacy Policy
167251

168-
| Variable | Required | Description |
169-
|----------|----------|-------------|
170-
| `DB_PATH` | Yes | Absolute path to the `.tracker.db` file |
252+
saga-mcp is a fully local, offline tool. It does **not**:
253+
254+
- Collect any user data
255+
- Send any data to external servers
256+
- Require internet access after installation
257+
- Use analytics, telemetry, or tracking of any kind
258+
259+
All data is stored exclusively in the local SQLite file specified by `DB_PATH`. You own your data completely. Uninstalling saga-mcp and deleting the `.tracker.db` file removes all traces.
260+
261+
For questions about privacy, open an issue at https://github.com/spranab/saga-mcp/issues.
171262

172263
## Development
173264

@@ -179,6 +270,11 @@ npm run build
179270
DB_PATH=./test.db npm start
180271
```
181272

273+
## Support
274+
275+
- **Issues**: https://github.com/spranab/saga-mcp/issues
276+
- **Repository**: https://github.com/spranab/saga-mcp
277+
182278
## License
183279

184280
MIT

‎manifest.json‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
{
2+
"manifest_version": "0.3",
3+
"name": "saga-mcp",
4+
"display_name": "Saga — Project Tracker for AI Agents",
5+
"version": "1.1.0",
6+
"description": "A Jira-like project tracker MCP server for AI agents. SQLite-backed, per-project scoped, with full hierarchy and activity logging — so LLMs never lose track.",
7+
"long_description": "Saga gives your AI assistant a structured SQLite database to track projects, epics, tasks, subtasks, notes, and decisions across sessions. No more scattered markdown files — one `tracker_dashboard` call gives full project context to resume work.\n\n**Key features:**\n- Full hierarchy: Projects > Epics > Tasks > Subtasks\n- SQLite: Self-contained `.tracker.db` file per project — zero setup\n- Activity log: Every mutation is automatically tracked\n- Dashboard: One tool call gives full project overview\n- Notes system: Decisions, context, meeting notes, blockers\n- Batch operations: Create multiple subtasks or update multiple tasks in one call\n- 22 focused tools with safety annotations",
8+
"author": {
9+
"name": "spranab",
10+
"url": "https://github.com/spranab"
11+
},
12+
"repository": {
13+
"type": "git",
14+
"url": "https://github.com/spranab/saga-mcp.git"
15+
},
16+
"homepage": "https://github.com/spranab/saga-mcp#readme",
17+
"documentation": "https://github.com/spranab/saga-mcp#readme",
18+
"support": "https://github.com/spranab/saga-mcp/issues",
19+
"keywords": [
20+
"mcp",
21+
"project-tracker",
22+
"task-manager",
23+
"sqlite",
24+
"jira-alternative",
25+
"ai-agent",
26+
"llm-tools",
27+
"model-context-protocol"
28+
],
29+
"license": "MIT",
30+
"privacy_policies": [],
31+
"server": {
32+
"type": "node",
33+
"entry_point": "dist/index.js",
34+
"mcp_config": {
35+
"command": "node",
36+
"args": ["${__dirname}/dist/index.js"],
37+
"env": {
38+
"DB_PATH": "${user_config.db_path}"
39+
}
40+
}
41+
},
42+
"tools": [
43+
{ "name": "tracker_init", "description": "Initialize tracker and create first project" },
44+
{ "name": "tracker_dashboard", "description": "Full project overview — call this first when resuming work" },
45+
{ "name": "project_create", "description": "Create a new project" },
46+
{ "name": "project_list", "description": "List projects with completion stats" },
47+
{ "name": "project_update", "description": "Update project (archive to soft-delete)" },
48+
{ "name": "epic_create", "description": "Create an epic within a project" },
49+
{ "name": "epic_list", "description": "List epics with task counts" },
50+
{ "name": "epic_update", "description": "Update an epic" },
51+
{ "name": "task_create", "description": "Create a task within an epic" },
52+
{ "name": "task_list", "description": "List/filter tasks by epic, status, priority, assignee, tag" },
53+
{ "name": "task_get", "description": "Get task with subtasks and related notes" },
54+
{ "name": "task_update", "description": "Update task (status changes auto-logged)" },
55+
{ "name": "task_batch_update", "description": "Update multiple tasks at once" },
56+
{ "name": "subtask_create", "description": "Create subtask(s) — supports batch" },
57+
{ "name": "subtask_update", "description": "Update subtask title/status" },
58+
{ "name": "subtask_delete", "description": "Delete subtask(s) — supports batch" },
59+
{ "name": "note_save", "description": "Create or update a note (upsert)" },
60+
{ "name": "note_list", "description": "List notes with filters" },
61+
{ "name": "note_search", "description": "Full-text search across notes" },
62+
{ "name": "note_delete", "description": "Delete a note" },
63+
{ "name": "tracker_search", "description": "Cross-entity search (projects, epics, tasks, notes)" },
64+
{ "name": "activity_log", "description": "View change history with filters" }
65+
],
66+
"compatibility": {
67+
"platforms": ["darwin", "win32", "linux"],
68+
"runtimes": {
69+
"node": ">=18.0.0"
70+
}
71+
},
72+
"user_config": {
73+
"db_path": {
74+
"type": "file",
75+
"title": "Database Path",
76+
"description": "Path to the .tracker.db SQLite file. The file and schema are auto-created on first use.",
77+
"required": true
78+
}
79+
}
80+
}

‎package.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "saga-mcp",
3-
"version": "1.1.0",
3+
"version": "1.2.0",
44
"description": "A Jira-like project tracker MCP server for AI agents. SQLite-backed, per-project scoped, with full hierarchy (Projects > Epics > Tasks > Subtasks), activity logging, and a dashboard — so LLMs never lose track.",
55
"type": "module",
66
"main": "dist/index.js",
@@ -9,7 +9,8 @@
99
},
1010
"files": [
1111
"dist",
12-
"README.md"
12+
"README.md",
13+
"manifest.json"
1314
],
1415
"scripts": {
1516
"build": "tsc",

0 commit comments

Comments
 (0)