{"id":27234450,"url":"https://github.com/bsmi021/mcp-task-manager-server","last_synced_at":"2025-07-06T13:04:37.892Z","repository":{"id":287020167,"uuid":"963340371","full_name":"bsmi021/mcp-task-manager-server","owner":"bsmi021","description":"A local Model Context Protocol (MCP) server providing backend tools for client-driven project and task management using a SQLite database.","archived":false,"fork":false,"pushed_at":"2025-06-11T14:37:22.000Z","size":123,"stargazers_count":12,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-06T13:04:37.097Z","etag":null,"topics":["claude","cline","mcp","modelcontextprotocol","roo","task","task-management","task-manager","taskmanager"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bsmi021.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-09T14:27:25.000Z","updated_at":"2025-07-01T22:55:12.000Z","dependencies_parsed_at":"2025-06-01T21:37:06.567Z","dependency_job_id":"01bcc093-62cb-4323-a516-c3352a83d294","html_url":"https://github.com/bsmi021/mcp-task-manager-server","commit_stats":null,"previous_names":["bsmi021/mcp-task-manager-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bsmi021/mcp-task-manager-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-task-manager-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-task-manager-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-task-manager-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-task-manager-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bsmi021","download_url":"https://codeload.github.com/bsmi021/mcp-task-manager-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-task-manager-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263905740,"owners_count":23527971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","cline","mcp","modelcontextprotocol","roo","task","task-management","task-manager","taskmanager"],"created_at":"2025-04-10T15:56:40.104Z","updated_at":"2025-07-06T13:04:37.866Z","avatar_url":"https://github.com/bsmi021.png","language":"TypeScript","funding_links":[],"categories":["📚 Projects (1974 total)","Other Tools and Integrations","🌐 Web Development"],"sub_categories":["MCP Servers","How to Submit"],"readme":"# MCP Task Manager Server\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"public/images/mcp-task-manager-logo.svg\" alt=\"MCP Task Manager Logo\" width=\"200\" height=\"200\" /\u003e\n\u003c/div\u003e\n\nA local Model Context Protocol (MCP) server providing backend tools for client-driven project and task management using a SQLite database.\n\n## Overview\n\nThis server acts as a persistent backend for local MCP clients (like AI agents or scripts) that need to manage structured task data within distinct projects. It handles data storage and provides a standardized set of tools for interaction, while the strategic workflow logic resides within the client.\n\n**Key Features:**\n\n* **Project-Based:** Tasks are organized within distinct projects.\n* **SQLite Persistence:** Uses a local SQLite file (`./data/taskmanager.db` by default) for simple, self-contained data storage.\n* **Client-Driven:** Provides tools for clients; does not dictate workflow.\n* **MCP Compliant:** Adheres to the Model Context Protocol for tool definition and communication.\n* **Task Management:** Supports creating projects, adding tasks, listing/showing tasks, updating status, expanding tasks into subtasks, and identifying the next actionable task.\n* **Import/Export:** Allows exporting project data to JSON and importing from JSON to create new projects.\n\n## Implemented MCP Tools\n\nThe following tools are available for MCP clients:\n\n* **`createProject`**:\n  * **Description:** Creates a new, empty project.\n  * **Params:** `projectName` (string, optional, max 255)\n  * **Returns:** `{ project_id: string }`\n* **`addTask`**:\n  * **Description:** Adds a new task to a project.\n  * **Params:** `project_id` (string, required, UUID), `description` (string, required, 1-1024), `dependencies` (string[], optional, max 50), `priority` (enum 'high'|'medium'|'low', optional, default 'medium'), `status` (enum 'todo'|'in-progress'|'review'|'done', optional, default 'todo')\n  * **Returns:** Full `TaskData` object of the created task.\n* **`listTasks`**:\n  * **Description:** Lists tasks for a project, with optional filtering and subtask inclusion.\n  * **Params:** `project_id` (string, required, UUID), `status` (enum 'todo'|'in-progress'|'review'|'done', optional), `include_subtasks` (boolean, optional, default false)\n  * **Returns:** Array of `TaskData` or `StructuredTaskData` objects.\n* **`showTask`**:\n  * **Description:** Retrieves full details for a specific task, including dependencies and direct subtasks.\n  * **Params:** `project_id` (string, required, UUID), `task_id` (string, required)\n  * **Returns:** `FullTaskData` object.\n* **`setTaskStatus`**:\n  * **Description:** Updates the status of one or more tasks.\n  * **Params:** `project_id` (string, required, UUID), `task_ids` (string[], required, 1-100), `status` (enum 'todo'|'in-progress'|'review'|'done', required)\n  * **Returns:** `{ success: true, updated_count: number }`\n* **`expandTask`**:\n  * **Description:** Breaks a parent task into subtasks, optionally replacing existing ones.\n  * **Params:** `project_id` (string, required, UUID), `task_id` (string, required), `subtask_descriptions` (string[], required, 1-20, each 1-512), `force` (boolean, optional, default false)\n  * **Returns:** Updated parent `FullTaskData` object including new subtasks.\n* **`getNextTask`**:\n  * **Description:** Identifies the next actionable task based on status ('todo'), dependencies ('done'), priority, and creation date.\n  * **Params:** `project_id` (string, required, UUID)\n  * **Returns:** `FullTaskData` object of the next task, or `null` if none are ready.\n* **`exportProject`**:\n  * **Description:** Exports complete project data as a JSON string.\n  * **Params:** `project_id` (string, required, UUID), `format` (enum 'json', optional, default 'json')\n  * **Returns:** JSON string representing the project.\n* **`importProject`**:\n  * **Description:** Creates a *new* project from an exported JSON string.\n  * **Params:** `project_data` (string, required, JSON), `new_project_name` (string, optional, max 255)\n  * **Returns:** `{ project_id: string }` of the newly created project.\n* **`updateTask`**:\n  * **Description:** Updates specific details (description, priority, dependencies) of an existing task.\n  * **Params:** `project_id` (string, required, UUID), `task_id` (string, required, UUID), `description` (string, optional, 1-1024), `priority` (enum 'high'|'medium'|'low', optional), `dependencies` (string[], optional, max 50, replaces existing)\n  * **Returns:** Updated `FullTaskData` object.\n* **`deleteTask`**:\n  * **Description:** Deletes one or more tasks (and their subtasks/dependency links via cascade).\n  * **Params:** `project_id` (string, required, UUID), `task_ids` (string[], required, 1-100)\n  * **Returns:** `{ success: true, deleted_count: number }`\n* **`deleteProject`**:\n  * **Description:** Permanently deletes a project and ALL associated data. **Use with caution!**\n  * **Params:** `project_id` (string, required, UUID)\n  * **Returns:** `{ success: true }`\n\n*(Note: Refer to the corresponding `src/tools/*Params.ts` files for detailed Zod schemas and parameter descriptions.)*\n\n## Getting Started\n\n1. **Prerequisites:** Node.js (LTS recommended), npm.\n2. **Install Dependencies:**\n\n    ```bash\n    npm install\n    ```\n\n3. **Run in Development Mode:** (Uses `ts-node` and `nodemon` for auto-reloading)\n\n    ```bash\n    npm run dev\n    ```\n\n    The server will connect via stdio. Logs (JSON format) will be printed to stderr. The SQLite database will be created/updated in `./data/taskmanager.db`.\n4. **Build for Production:**\n\n    ```bash\n    npm run build\n    ```\n\n5. **Run Production Build:**\n\n    ```bash\n    npm start\n    ```\n\n## Configuration\n\n* **Database Path:** The location of the SQLite database file can be overridden by setting the `DATABASE_PATH` environment variable. The default is `./data/taskmanager.db`.\n* **Log Level:** The logging level can be set using the `LOG_LEVEL` environment variable (e.g., `debug`, `info`, `warn`, `error`). The default is `info`.\n\n## Project Structure\n\n* `/src`: Source code.\n  * `/config`: Configuration management.\n  * `/db`: Database manager and schema (`schema.sql`).\n  * `/repositories`: Data access layer (SQLite interaction).\n  * `/services`: Core business logic.\n  * `/tools`: MCP tool definitions (*Params.ts) and implementation (*Tool.ts).\n  * `/types`: Shared TypeScript interfaces (currently minimal, mostly in repos/services).\n  * `/utils`: Logging, custom errors, etc.\n  * `createServer.ts`: Server instance creation.\n  * `server.ts`: Main application entry point.\n* `/dist`: Compiled JavaScript output.\n* `/docs`: Project documentation (PRD, Feature Specs, RFC).\n* `/data`: Default location for the SQLite database file (created automatically).\n* `tasks.md`: Manual task tracking file for development.\n* Config files (`package.json`, `tsconfig.json`, `.eslintrc.json`, etc.)\n\n## Linting and Formatting\n\n* **Lint:** `npm run lint`\n* **Format:** `npm run format`\n\n(Code is automatically linted/formatted on commit via Husky/lint-staged).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsmi021%2Fmcp-task-manager-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbsmi021%2Fmcp-task-manager-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsmi021%2Fmcp-task-manager-server/lists"}