agent-task-manager-mcp 1.0.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/LICENSE.md +65 -0
- package/README.md +473 -0
- package/dist/db.d.ts +4 -0
- package/dist/db.d.ts.map +1 -0
- package/dist/db.js +20 -0
- package/dist/db.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +73 -0
- package/dist/index.js.map +1 -0
- package/dist/models/Checkpoint.d.ts +15 -0
- package/dist/models/Checkpoint.d.ts.map +1 -0
- package/dist/models/Checkpoint.js +47 -0
- package/dist/models/Checkpoint.js.map +1 -0
- package/dist/models/Session.d.ts +24 -0
- package/dist/models/Session.d.ts.map +1 -0
- package/dist/models/Session.js +58 -0
- package/dist/models/Session.js.map +1 -0
- package/dist/models/Subtask.d.ts +25 -0
- package/dist/models/Subtask.d.ts.map +1 -0
- package/dist/models/Subtask.js +63 -0
- package/dist/models/Subtask.js.map +1 -0
- package/dist/models/Task.d.ts +31 -0
- package/dist/models/Task.d.ts.map +1 -0
- package/dist/models/Task.js +66 -0
- package/dist/models/Task.js.map +1 -0
- package/dist/schemas/zod.schemas.d.ts +344 -0
- package/dist/schemas/zod.schemas.d.ts.map +1 -0
- package/dist/schemas/zod.schemas.js +106 -0
- package/dist/schemas/zod.schemas.js.map +1 -0
- package/dist/tools/checkpoint.tools.d.ts +4 -0
- package/dist/tools/checkpoint.tools.d.ts.map +1 -0
- package/dist/tools/checkpoint.tools.js +69 -0
- package/dist/tools/checkpoint.tools.js.map +1 -0
- package/dist/tools/session.tools.d.ts +4 -0
- package/dist/tools/session.tools.d.ts.map +1 -0
- package/dist/tools/session.tools.js +127 -0
- package/dist/tools/session.tools.js.map +1 -0
- package/dist/tools/subtask.tools.d.ts +4 -0
- package/dist/tools/subtask.tools.d.ts.map +1 -0
- package/dist/tools/subtask.tools.js +126 -0
- package/dist/tools/subtask.tools.js.map +1 -0
- package/dist/tools/task.tools.d.ts +4 -0
- package/dist/tools/task.tools.d.ts.map +1 -0
- package/dist/tools/task.tools.js +202 -0
- package/dist/tools/task.tools.js.map +1 -0
- package/package.json +43 -0
package/LICENSE.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
CUSTOM SOFTWARE LICENSE
|
|
2
|
+
Version 1.0
|
|
3
|
+
|
|
4
|
+
Copyright (c) 2026
|
|
5
|
+
All rights reserved.
|
|
6
|
+
|
|
7
|
+
1. Definitions
|
|
8
|
+
|
|
9
|
+
"Software" means all source code, object code, files, documentation, and other materials in this repository.
|
|
10
|
+
|
|
11
|
+
"Personal Use" means use by a natural person for private, non-commercial, educational, hobby, evaluation, or research purposes, where such use is not performed for or on behalf of a business, employer, organization, or other commercial entity.
|
|
12
|
+
|
|
13
|
+
"Commercial Use" means any use of the Software, directly or indirectly, for commercial advantage, monetary compensation, internal business operations, client work, product development, hosted services, or any use by or for a company, organization, government entity, or other legal entity.
|
|
14
|
+
|
|
15
|
+
"Company" means any corporation, limited liability company, partnership, sole proprietorship, nonprofit, government entity, educational institution, or other legal entity, including any affiliate, parent, or subsidiary acting together.
|
|
16
|
+
|
|
17
|
+
"Company Valuation" means:
|
|
18
|
+
(a) for a publicly traded company, its market capitalization; and
|
|
19
|
+
(b) for a privately held company, its most recent bona fide post-money valuation established in an equity financing, acquisition, or similar arm’s-length transaction.
|
|
20
|
+
If no reliable valuation can be determined, the company will be deemed to exceed the threshold if it has annual gross revenue greater than USD 10,000,000.
|
|
21
|
+
|
|
22
|
+
"Threshold Company" means any Company with a Company Valuation greater than USD 10,000,000.
|
|
23
|
+
|
|
24
|
+
2. License Grant for Personal Use
|
|
25
|
+
|
|
26
|
+
Subject to this License, you are granted a limited, non-exclusive, non-transferable, non-sublicensable, revocable license to use, copy, modify, and run the Software solely for Personal Use.
|
|
27
|
+
|
|
28
|
+
3. No Commercial Rights for Threshold Companies
|
|
29
|
+
|
|
30
|
+
No right, license, or permission is granted under this License for any Commercial Use by a Threshold Company.
|
|
31
|
+
|
|
32
|
+
Any Threshold Company wishing to use the Software for any Commercial Use must obtain a separate paid commercial license from the Licensor before using, copying, modifying, distributing, deploying, or making the Software available.
|
|
33
|
+
|
|
34
|
+
4. Commercial Use by Other Entities
|
|
35
|
+
|
|
36
|
+
Except as expressly permitted by a separate written agreement from the Licensor, no Commercial Use is permitted under this License.
|
|
37
|
+
|
|
38
|
+
5. Distribution Restrictions
|
|
39
|
+
|
|
40
|
+
You may not sell, sublicense, rent, lease, host as a service, redistribute, or make the Software available to any third party for Commercial Use without the Licensor’s prior written permission.
|
|
41
|
+
|
|
42
|
+
6. Ownership
|
|
43
|
+
|
|
44
|
+
The Software is licensed, not sold. The Licensor retains all right, title, and interest in and to the Software, including all intellectual property rights.
|
|
45
|
+
|
|
46
|
+
7. Termination
|
|
47
|
+
|
|
48
|
+
This License terminates automatically if you violate any term of this License. Upon termination, you must stop using the Software and delete all copies in your possession or control.
|
|
49
|
+
|
|
50
|
+
8. No Warranty
|
|
51
|
+
|
|
52
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.
|
|
53
|
+
|
|
54
|
+
9. Limitation of Liability
|
|
55
|
+
|
|
56
|
+
TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT, OR OTHERWISE, ARISING FROM OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF THE SOFTWARE.
|
|
57
|
+
|
|
58
|
+
10. Commercial Licensing Contact
|
|
59
|
+
|
|
60
|
+
For commercial licensing requests, contact:
|
|
61
|
+
mmlnima@gmail.com
|
|
62
|
+
|
|
63
|
+
11. Governing Law
|
|
64
|
+
|
|
65
|
+
This License shall be governed by the laws of Germany, without regard to conflict of law principles.
|
package/README.md
ADDED
|
@@ -0,0 +1,473 @@
|
|
|
1
|
+
# Agent Task Manager MCP
|
|
2
|
+
|
|
3
|
+
**Enterprise-grade MCP server for managing long-running AI agent tasks across context windows and memory boundaries.**
|
|
4
|
+
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
[](https://modelcontextprotocol.io/)
|
|
7
|
+
[](https://mongoosejs.com/)
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install -g agent-task-manager-mcp
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Table of Contents
|
|
16
|
+
|
|
17
|
+
- [The Problem](#the-problem)
|
|
18
|
+
- [The Solution](#the-solution)
|
|
19
|
+
- [Architecture Overview](#architecture-overview)
|
|
20
|
+
- [How It Works](#how-it-works)
|
|
21
|
+
- [Features](#features)
|
|
22
|
+
- [Quick Start](#quick-start)
|
|
23
|
+
- [Configuration](#configuration)
|
|
24
|
+
- [Integration](#integration)
|
|
25
|
+
- [Tool Reference](#tool-reference)
|
|
26
|
+
- [Data Model](#data-model)
|
|
27
|
+
- [Security](#security)
|
|
28
|
+
- [Troubleshooting](#troubleshooting)
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## The Problem
|
|
33
|
+
|
|
34
|
+
### Context Window Limitation
|
|
35
|
+
|
|
36
|
+
AI agents operate within a fixed **context window** (e.g., 100K–200K tokens). Long-running tasks—building a full-stack app, migrating a codebase, implementing 50+ features—exceed this limit. When the context fills up:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
40
|
+
│ AGENT CONTEXT WINDOW (e.g., 128K tokens) │
|
|
41
|
+
├─────────────────────────────────────────────────────────────────────────┤
|
|
42
|
+
│ [System Prompt] [Task Spec] [Code] [History] [Current Work] ... │
|
|
43
|
+
│ │
|
|
44
|
+
│ ═══════════════════════════════════════════► CONTEXT FULL │
|
|
45
|
+
│ │ │
|
|
46
|
+
│ ▼ │
|
|
47
|
+
│ Agent "forgets" earlier work │
|
|
48
|
+
│ No persistent state │
|
|
49
|
+
│ Duplicate effort │
|
|
50
|
+
│ Inconsistent handoffs │
|
|
51
|
+
└─────────────────────────────────────────────────────────────────────────┘
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Consequences
|
|
55
|
+
|
|
56
|
+
| Issue | Impact |
|
|
57
|
+
| ------------------- | --------------------------------------------- |
|
|
58
|
+
| **No persistence** | Agent state is lost when context resets |
|
|
59
|
+
| **No handoff** | New agent instance has no idea what was done |
|
|
60
|
+
| **Duplicate work** | Same features implemented multiple times |
|
|
61
|
+
| **No coordination** | Multiple agents can pick the same task |
|
|
62
|
+
| **No audit trail** | No record of sessions, progress, or decisions |
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## The Solution
|
|
67
|
+
|
|
68
|
+
**Agent Task Manager MCP** provides a **persistent task orchestration layer** that lets agents:
|
|
69
|
+
|
|
70
|
+
1. **Create and decompose** large tasks into atomic subtasks
|
|
71
|
+
2. **Track progress** across sessions with evidence-based verification
|
|
72
|
+
3. **Hand off cleanly** via structured progress notes and checkpoints
|
|
73
|
+
4. **Coordinate** via task locking to prevent duplicate work
|
|
74
|
+
5. **Recover** from failures using named checkpoints
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
78
|
+
│ AGENT TASK MANAGER MCP │
|
|
79
|
+
├──────────────────────────────────────────────────────────────────────────────────┤
|
|
80
|
+
│ │
|
|
81
|
+
│ Agent Session 1 Agent Session 2 Agent Session 3 │
|
|
82
|
+
│ (Context Full) (Fresh Context) (Fresh Context) │
|
|
83
|
+
│ │ │ │ │
|
|
84
|
+
│ │ task_lock │ session_start │ subtask_get_next │
|
|
85
|
+
│ │ session_start │ lastProgressNote ◄─────┼── Continuity! │
|
|
86
|
+
│ │ subtask_get_next │ subtask_get_next │ │
|
|
87
|
+
│ │ [do work] │ [do work] │ │
|
|
88
|
+
│ │ subtask_update_status │ checkpoint_save │ │
|
|
89
|
+
│ │ session_end │ session_end │ │
|
|
90
|
+
│ │ task_unlock │ task_unlock │ │
|
|
91
|
+
│ │ │ │ │
|
|
92
|
+
│ └─────────────────────────┴─────────────────────────┘ │
|
|
93
|
+
│ │ │
|
|
94
|
+
│ ▼ │
|
|
95
|
+
│ ┌───────────────────────────────┐ │
|
|
96
|
+
│ │ MongoDB │ │
|
|
97
|
+
│ │ Tasks • Subtasks • Sessions │ │
|
|
98
|
+
│ │ Checkpoints • Progress │ │
|
|
99
|
+
│ └───────────────────────────────┘ │
|
|
100
|
+
│ │
|
|
101
|
+
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Architecture Overview
|
|
107
|
+
|
|
108
|
+
### System Diagram
|
|
109
|
+
|
|
110
|
+
```mermaid
|
|
111
|
+
flowchart TB
|
|
112
|
+
subgraph Client["AI Client (Claude, Cursor, etc.)"]
|
|
113
|
+
Agent[AI Agent]
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
subgraph MCP["agent-task-manager-mcp"]
|
|
117
|
+
Server[MCP Server]
|
|
118
|
+
Tools[14 Tools]
|
|
119
|
+
Server --> Tools
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
subgraph Storage["Persistence"]
|
|
123
|
+
MongoDB[(MongoDB)]
|
|
124
|
+
end
|
|
125
|
+
|
|
126
|
+
Agent <-->|stdio/JSON-RPC| Server
|
|
127
|
+
Server <-->|Mongoose| MongoDB
|
|
128
|
+
|
|
129
|
+
subgraph ToolsDetail["Tool Categories"]
|
|
130
|
+
T1[task_*]
|
|
131
|
+
T2[subtask_*]
|
|
132
|
+
T3[session_*]
|
|
133
|
+
T4[checkpoint_*]
|
|
134
|
+
end
|
|
135
|
+
Tools --> ToolsDetail
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Component Flow
|
|
139
|
+
|
|
140
|
+
```mermaid
|
|
141
|
+
flowchart LR
|
|
142
|
+
subgraph Init["Init Phase"]
|
|
143
|
+
A1[task_create]
|
|
144
|
+
A2[task_lock]
|
|
145
|
+
A3[session_start]
|
|
146
|
+
A4[subtask_create_bulk]
|
|
147
|
+
A5[task_update]
|
|
148
|
+
A6[session_end]
|
|
149
|
+
A7[task_unlock]
|
|
150
|
+
end
|
|
151
|
+
|
|
152
|
+
subgraph Exec["Execution Phase"]
|
|
153
|
+
B1[task_lock]
|
|
154
|
+
B2[session_start]
|
|
155
|
+
B3[subtask_get_next]
|
|
156
|
+
B4[subtask_update_status]
|
|
157
|
+
B5[checkpoint_save]
|
|
158
|
+
B6[session_end]
|
|
159
|
+
B7[task_unlock]
|
|
160
|
+
end
|
|
161
|
+
|
|
162
|
+
Init --> Exec
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## How It Works
|
|
168
|
+
|
|
169
|
+
### Two-Phase Workflow
|
|
170
|
+
|
|
171
|
+
| Phase | Purpose | When |
|
|
172
|
+
| ------------- | ------------------------------------------------- | ------------------------ |
|
|
173
|
+
| **Init** | Analyze spec, create subtask list, set up context | First session only |
|
|
174
|
+
| **Execution** | Work on subtasks incrementally, verify, hand off | Every subsequent session |
|
|
175
|
+
|
|
176
|
+
### Session Lifecycle (Visual)
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
┌─────────────────────────────────────────────────────────┐
|
|
180
|
+
│ SESSION START │
|
|
181
|
+
└─────────────────────────────────────────────────────────┘
|
|
182
|
+
│
|
|
183
|
+
┌─────────────────────────┼─────────────────────────┐
|
|
184
|
+
│ ▼ │
|
|
185
|
+
│ task_lock(agentId) │
|
|
186
|
+
│ │ │
|
|
187
|
+
│ ▼ │
|
|
188
|
+
│ session_start(phase) │
|
|
189
|
+
│ │ │
|
|
190
|
+
│ ▼ │
|
|
191
|
+
│ ┌─── Read lastProgressNote ───┐ │
|
|
192
|
+
│ │ Run initScript if present │ │
|
|
193
|
+
│ └─────────────────────────────┘ │
|
|
194
|
+
│ │ │
|
|
195
|
+
│ ▼ │
|
|
196
|
+
│ subtask_get_next() │
|
|
197
|
+
│ │ │
|
|
198
|
+
│ ┌──────────┴─────────┐ │
|
|
199
|
+
│ │ │ │
|
|
200
|
+
│ null (done) subtask │
|
|
201
|
+
│ │ │ │
|
|
202
|
+
│ ▼ ▼ │
|
|
203
|
+
│ task_update(completed) [DO THE WORK] │
|
|
204
|
+
│ │ │ │
|
|
205
|
+
│ │ ▼ │
|
|
206
|
+
│ │ subtask_update_status │
|
|
207
|
+
│ │ (passed/failed + evidence) │
|
|
208
|
+
│ │ │ │
|
|
209
|
+
│ │ ▼ │
|
|
210
|
+
│ │ checkpoint_save (optional) │
|
|
211
|
+
│ │ │ │
|
|
212
|
+
│ │ └──► loop │
|
|
213
|
+
│ │ back │
|
|
214
|
+
│ │ │
|
|
215
|
+
└──────────────┼────────────────────────────────────┘
|
|
216
|
+
│
|
|
217
|
+
▼
|
|
218
|
+
┌──────────────────────────────────────────────────┐
|
|
219
|
+
│ SESSION END │
|
|
220
|
+
│ session_end(progressNote, gitCommit, ...) │
|
|
221
|
+
│ task_unlock(agentId) │
|
|
222
|
+
└──────────────────────────────────────────────────┘
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Problem → Solution Mapping
|
|
226
|
+
|
|
227
|
+
| Problem | Solution |
|
|
228
|
+
| ------------------- | ------------------------------------------------------------------------- |
|
|
229
|
+
| Context overflow | `session_end` writes `progressNote`; next agent reads via `session_start` |
|
|
230
|
+
| Lost state | `checkpoint_save` / `checkpoint_restore` for rollback points |
|
|
231
|
+
| Duplicate work | `task_lock` / `task_unlock` for exclusive ownership |
|
|
232
|
+
| Unclear what's done | `subtask_update_status` with `evidence` (required for passed) |
|
|
233
|
+
| Dependency ordering | `subtask_create_bulk` with `dependsOn`; `subtask_get_next` respects it |
|
|
234
|
+
| No continuity | `lastProgressNote` + `lastGitCommit` returned by `session_start` |
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## Features
|
|
239
|
+
|
|
240
|
+
- **14 MCP tools** for full task lifecycle
|
|
241
|
+
- **MongoDB persistence** with Mongoose ODM
|
|
242
|
+
- **Zod validation** on all tool inputs
|
|
243
|
+
- **Task locking** for multi-agent coordination
|
|
244
|
+
- **Evidence-based verification** (no passing without proof)
|
|
245
|
+
- **Checkpoint/restore** for risky operations
|
|
246
|
+
- **Session handoff** with structured progress notes
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## Quick Start
|
|
251
|
+
|
|
252
|
+
### Prerequisites
|
|
253
|
+
|
|
254
|
+
- **Node.js** 18+
|
|
255
|
+
- **MongoDB** 6+ (local, remote IP, or Atlas)
|
|
256
|
+
- **MCP-compatible client** (Claude Desktop, Cursor, etc.)
|
|
257
|
+
|
|
258
|
+
### Installation
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
git clone <repository-url>
|
|
262
|
+
cd agent-task-manager-mcp
|
|
263
|
+
npm install
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
### Environment Setup
|
|
267
|
+
|
|
268
|
+
(optional and can be define in MCP config of the agent in MONGODB_URI)
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
cp .env.example .env
|
|
272
|
+
# Edit .env and set MONGODB_URI
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
### Run
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
# Production (compiled)
|
|
279
|
+
npm run build
|
|
280
|
+
npm start
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## Configuration
|
|
286
|
+
|
|
287
|
+
### Environment Variables
|
|
288
|
+
|
|
289
|
+
| Variable | Required | Description | Example |
|
|
290
|
+
| ------------- | -------- | ------------------------- | --------------------------------------- |
|
|
291
|
+
| `MONGODB_URI` | Yes | MongoDB connection string | `mongodb://localhost:27017/agent-tasks` |
|
|
292
|
+
|
|
293
|
+
### MongoDB URI Examples
|
|
294
|
+
|
|
295
|
+
```env
|
|
296
|
+
# Local
|
|
297
|
+
MONGODB_URI=mongodb://localhost:27017/agent-tasks
|
|
298
|
+
|
|
299
|
+
# Remote IP (agent on IP1, MongoDB on IP2)
|
|
300
|
+
MONGODB_URI=mongodb://user:password@IP2:27017/agent-tasks?authSource=admin
|
|
301
|
+
|
|
302
|
+
# MongoDB Atlas (cloud)
|
|
303
|
+
MONGODB_URI=mongodb+srv://user:password@cluster.mongodb.net/agent-tasks?retryWrites=true&w=majority
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
> **Note:** URL-encode special characters in passwords (e.g., `@` → `%40`).
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## Integration
|
|
311
|
+
|
|
312
|
+
### Claude Desktop
|
|
313
|
+
|
|
314
|
+
Add to `claude_desktop_config.json`:
|
|
315
|
+
|
|
316
|
+
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
317
|
+
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
318
|
+
|
|
319
|
+
```json
|
|
320
|
+
{
|
|
321
|
+
"mcpServers": {
|
|
322
|
+
"agent-task-manager-mcp": {
|
|
323
|
+
"command": "npx",
|
|
324
|
+
"args": ["tsx", "C:/path/to/agent-task-manager-mcp/src/index.ts"],
|
|
325
|
+
"env": {
|
|
326
|
+
"MONGODB_URI": "mongodb://localhost:27017/agent-tasks"
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
### Cursor
|
|
334
|
+
|
|
335
|
+
Add to Cursor MCP settings (or `.cursor/mcp.json`):
|
|
336
|
+
|
|
337
|
+
```json
|
|
338
|
+
{
|
|
339
|
+
"mcpServers": {
|
|
340
|
+
"agent-task-manager-mcp": {
|
|
341
|
+
"command": "npx",
|
|
342
|
+
"args": ["tsx", "C:/path/to/agent-task-manager-mcp/src/index.ts"],
|
|
343
|
+
"env": {
|
|
344
|
+
"MONGODB_URI": "mongodb://localhost:27017/agent-tasks"
|
|
345
|
+
}
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
## Tool Reference
|
|
354
|
+
|
|
355
|
+
### Task Tools (7)
|
|
356
|
+
|
|
357
|
+
| Tool | Description |
|
|
358
|
+
| ------------- | -------------------------------------------------------------------- |
|
|
359
|
+
| `task_create` | Create top-level task; returns ID for all subsequent ops |
|
|
360
|
+
| `task_get` | Get task by ID with subtask summary (total, passed, failed, pending) |
|
|
361
|
+
| `task_list` | List tasks with filters (status, phase, tags, pagination) |
|
|
362
|
+
| `task_update` | Update status, phase, context, metadata |
|
|
363
|
+
| `task_delete` | Permanently delete task and all related data |
|
|
364
|
+
| `task_lock` | Claim exclusive ownership for agentId |
|
|
365
|
+
| `task_unlock` | Release ownership |
|
|
366
|
+
|
|
367
|
+
### Subtask Tools (3)
|
|
368
|
+
|
|
369
|
+
| Tool | Description |
|
|
370
|
+
| ----------------------- | ----------------------------------------------------------- |
|
|
371
|
+
| `subtask_create_bulk` | Create full subtask list in one call; supports `dependsOn` |
|
|
372
|
+
| `subtask_get_next` | Get next pending subtask (deps satisfied, highest priority) |
|
|
373
|
+
| `subtask_update_status` | Mark passed/failed/blocked; `evidence` required for passed |
|
|
374
|
+
|
|
375
|
+
### Session Tools (2)
|
|
376
|
+
|
|
377
|
+
| Tool | Description |
|
|
378
|
+
| --------------- | -------------------------------------------------------- |
|
|
379
|
+
| `session_start` | Begin session; returns task, lastProgressNote, sessionId |
|
|
380
|
+
| `session_end` | Close session with progressNote, gitCommit, status |
|
|
381
|
+
|
|
382
|
+
### Checkpoint Tools (2)
|
|
383
|
+
|
|
384
|
+
| Tool | Description |
|
|
385
|
+
| -------------------- | ------------------------------------------- |
|
|
386
|
+
| `checkpoint_save` | Save named snapshot before risky operations |
|
|
387
|
+
| `checkpoint_restore` | Restore most recent checkpoint by label |
|
|
388
|
+
|
|
389
|
+
---
|
|
390
|
+
|
|
391
|
+
## Data Model
|
|
392
|
+
|
|
393
|
+
```
|
|
394
|
+
Task
|
|
395
|
+
├── title, description, status, phase, priority, tags
|
|
396
|
+
├── agentId, lockedAt (locking)
|
|
397
|
+
├── context: { workingDirectory, initScript, repoUrl, environmentVars }
|
|
398
|
+
├── metadata, deadline, completedAt
|
|
399
|
+
└── 1:N → Subtask, Session
|
|
400
|
+
|
|
401
|
+
Subtask
|
|
402
|
+
├── taskId, title, description, category, steps
|
|
403
|
+
├── status, priority, dependsOn[], agentId
|
|
404
|
+
├── attempts, lastError, evidence
|
|
405
|
+
└── category: functional | ui | performance | security | test
|
|
406
|
+
|
|
407
|
+
Session
|
|
408
|
+
├── taskId, agentId, phase
|
|
409
|
+
├── startedAt, endedAt, status
|
|
410
|
+
├── subtasksAttempted[], subtasksCompleted[]
|
|
411
|
+
├── progressNote, gitCommit, tokenCount
|
|
412
|
+
└── status: active | completed | crashed | timed_out
|
|
413
|
+
|
|
414
|
+
Checkpoint
|
|
415
|
+
├── taskId, sessionId, label
|
|
416
|
+
└── snapshot (JSON)
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
---
|
|
420
|
+
|
|
421
|
+
## Security
|
|
422
|
+
|
|
423
|
+
| Consideration | Recommendation |
|
|
424
|
+
| ----------------------- | -------------------------------------------------------------- |
|
|
425
|
+
| **MongoDB credentials** | Use env vars; never commit `.env` |
|
|
426
|
+
| **Network** | Use TLS for remote MongoDB; allow only trusted IPs in firewall |
|
|
427
|
+
| **Task locking** | Use unique `agentId` per instance to avoid conflicts |
|
|
428
|
+
| **Sensitive data** | Avoid storing secrets in `metadata` or `snapshot` |
|
|
429
|
+
|
|
430
|
+
---
|
|
431
|
+
|
|
432
|
+
## Troubleshooting
|
|
433
|
+
|
|
434
|
+
| Issue | Check |
|
|
435
|
+
| ----------------------------- | ------------------------------------------------------------------------ |
|
|
436
|
+
| `MONGODB_URI is not set` | Ensure `.env` exists and is loaded; verify env in MCP config |
|
|
437
|
+
| Connection refused | MongoDB running? Correct host/port? |
|
|
438
|
+
| Auth failed | Verify username/password; URL-encode special chars |
|
|
439
|
+
| Tool returns `success: false` | Inspect `error` field in JSON response |
|
|
440
|
+
| Task already locked | Another agent holds lock; wait or use `task_unlock` with correct agentId |
|
|
441
|
+
|
|
442
|
+
---
|
|
443
|
+
|
|
444
|
+
## Project Structure
|
|
445
|
+
|
|
446
|
+
```
|
|
447
|
+
agent-task-manager-mcp/
|
|
448
|
+
├── src/
|
|
449
|
+
│ ├── index.ts # MCP server entry point
|
|
450
|
+
│ ├── db.ts # MongoDB connection
|
|
451
|
+
│ ├── models/
|
|
452
|
+
│ │ ├── Task.ts
|
|
453
|
+
│ │ ├── Subtask.ts
|
|
454
|
+
│ │ ├── Session.ts
|
|
455
|
+
│ │ └── Checkpoint.ts
|
|
456
|
+
│ ├── tools/
|
|
457
|
+
│ │ ├── task.tools.ts
|
|
458
|
+
│ │ ├── subtask.tools.ts
|
|
459
|
+
│ │ ├── session.tools.ts
|
|
460
|
+
│ │ └── checkpoint.tools.ts
|
|
461
|
+
│ └── schemas/
|
|
462
|
+
│ └── zod.schemas.ts
|
|
463
|
+
├── package.json
|
|
464
|
+
├── tsconfig.json
|
|
465
|
+
├── .env.example
|
|
466
|
+
└── README.md
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## License
|
|
472
|
+
|
|
473
|
+
Custom Please read the License.md
|
package/dist/db.d.ts
ADDED
package/dist/db.d.ts.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AACA,OAAO,eAAe,CAAA;AAItB,QAAA,MAAM,SAAS,QAAa,OAAO,CAAC,IAAI,CASvC,CAAA;AAED,eAAe,SAAS,CAAA"}
|
package/dist/db.js
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
const mongoose_1 = __importDefault(require("mongoose"));
|
|
7
|
+
require("dotenv/config");
|
|
8
|
+
let isConnected = false;
|
|
9
|
+
const connectDB = async () => {
|
|
10
|
+
if (isConnected)
|
|
11
|
+
return;
|
|
12
|
+
const uri = process.env.MONGODB_URI;
|
|
13
|
+
if (!uri)
|
|
14
|
+
throw new Error('MONGODB_URI is not set in environment variables');
|
|
15
|
+
await mongoose_1.default.connect(uri);
|
|
16
|
+
isConnected = true;
|
|
17
|
+
console.error('[DB] Connected to MongoDB');
|
|
18
|
+
};
|
|
19
|
+
exports.default = connectDB;
|
|
20
|
+
//# sourceMappingURL=db.js.map
|
package/dist/db.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":";;;;;AAAA,wDAA+B;AAC/B,yBAAsB;AAEtB,IAAI,WAAW,GAAG,KAAK,CAAA;AAEvB,MAAM,SAAS,GAAG,KAAK,IAAmB,EAAE;IAC1C,IAAI,WAAW;QAAE,OAAM;IAEvB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAA;IACnC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;IAE5E,MAAM,kBAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC3B,WAAW,GAAG,IAAI,CAAA;IAClB,OAAO,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAA;AAC5C,CAAC,CAAA;AAED,kBAAe,SAAS,CAAA"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,eAAe,CAAA"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
|
|
7
|
+
const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
|
|
8
|
+
const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
|
|
9
|
+
require("dotenv/config");
|
|
10
|
+
const db_js_1 = __importDefault(require("./db.js"));
|
|
11
|
+
const task_tools_js_1 = require("./tools/task.tools.js");
|
|
12
|
+
const subtask_tools_js_1 = require("./tools/subtask.tools.js");
|
|
13
|
+
const session_tools_js_1 = require("./tools/session.tools.js");
|
|
14
|
+
const checkpoint_tools_js_1 = require("./tools/checkpoint.tools.js");
|
|
15
|
+
const allTools = [
|
|
16
|
+
...task_tools_js_1.taskToolDefinitions,
|
|
17
|
+
...subtask_tools_js_1.subtaskToolDefinitions,
|
|
18
|
+
...session_tools_js_1.sessionToolDefinitions,
|
|
19
|
+
...checkpoint_tools_js_1.checkpointToolDefinitions,
|
|
20
|
+
];
|
|
21
|
+
const server = new index_js_1.Server({ name: 'agent-task-manager-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
|
|
22
|
+
server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
|
|
23
|
+
tools: allTools,
|
|
24
|
+
}));
|
|
25
|
+
server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
|
|
26
|
+
const { name, arguments: args } = request.params;
|
|
27
|
+
try {
|
|
28
|
+
await (0, db_js_1.default)();
|
|
29
|
+
let result;
|
|
30
|
+
if (name.startsWith('task_')) {
|
|
31
|
+
result = await (0, task_tools_js_1.handleTaskTool)(name, args);
|
|
32
|
+
}
|
|
33
|
+
else if (name.startsWith('subtask_')) {
|
|
34
|
+
result = await (0, subtask_tools_js_1.handleSubtaskTool)(name, args);
|
|
35
|
+
}
|
|
36
|
+
else if (name.startsWith('session_')) {
|
|
37
|
+
result = await (0, session_tools_js_1.handleSessionTool)(name, args);
|
|
38
|
+
}
|
|
39
|
+
else if (name.startsWith('checkpoint_')) {
|
|
40
|
+
result = await (0, checkpoint_tools_js_1.handleCheckpointTool)(name, args);
|
|
41
|
+
}
|
|
42
|
+
else {
|
|
43
|
+
result = JSON.stringify({
|
|
44
|
+
success: false,
|
|
45
|
+
error: `Unknown tool: ${name}`,
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
return { content: [{ type: 'text', text: result }] };
|
|
49
|
+
}
|
|
50
|
+
catch (error) {
|
|
51
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
52
|
+
console.error(`[MCP] Tool "${name}" error:`, message);
|
|
53
|
+
return {
|
|
54
|
+
content: [
|
|
55
|
+
{
|
|
56
|
+
type: 'text',
|
|
57
|
+
text: JSON.stringify({ success: false, error: message }),
|
|
58
|
+
},
|
|
59
|
+
],
|
|
60
|
+
isError: true,
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
});
|
|
64
|
+
const main = async () => {
|
|
65
|
+
const transport = new stdio_js_1.StdioServerTransport();
|
|
66
|
+
await server.connect(transport);
|
|
67
|
+
console.error('[MCP] agent-task-manager-mcp server running on stdio');
|
|
68
|
+
};
|
|
69
|
+
main().catch((err) => {
|
|
70
|
+
console.error('[MCP] Fatal error:', err);
|
|
71
|
+
process.exit(1);
|
|
72
|
+
});
|
|
73
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import mongoose, { Document } from 'mongoose';
|
|
2
|
+
export interface ICheckpoint extends Document {
|
|
3
|
+
taskId: mongoose.Types.ObjectId;
|
|
4
|
+
sessionId: mongoose.Types.ObjectId;
|
|
5
|
+
label: string;
|
|
6
|
+
snapshot: Record<string, unknown>;
|
|
7
|
+
createdAt: Date;
|
|
8
|
+
updatedAt: Date;
|
|
9
|
+
}
|
|
10
|
+
export declare const Checkpoint: mongoose.Model<ICheckpoint, {}, {}, {}, mongoose.Document<unknown, {}, ICheckpoint, {}, {}> & ICheckpoint & Required<{
|
|
11
|
+
_id: mongoose.Types.ObjectId;
|
|
12
|
+
}> & {
|
|
13
|
+
__v: number;
|
|
14
|
+
}, any>;
|
|
15
|
+
//# sourceMappingURL=Checkpoint.d.ts.map
|