@jayakrishna007/managemate-mcp-server

Secure Model Context Protocol (MCP) Server bridge that allows developers to link their agentic coding environments (such as Claude Desktop, Cursor IDE, Copilot, and Windsurf) directly to their ManageMate workspace.

With this integration, your AI coding assistant can fetch assigned projects, list and paginate task backlogs, create new tasks, update statuses, manage dependencies, and view/add to your personal scratchpad todos—completely secure and under fine-grained permission scopes.

🚀 Key Features

• Fine-Grained Scopes: Fully enforces token-level scopes (projects:read, tasks:read, tasks:write, todos:read, todos:write).
• Project-Level Restrictions: Restricts the AI agent to accessing or modifying only specific, approved projects.
• Smart Native Backlog Filtering & Pagination: Includes built-in backend-level pagination, activeOnly, and deadlineDate filtering support for fetching tasks, preventing token-limit bloat in large codebases.
• Comprehensive Task & Todo CRUD with Optional Subtasks: Supports querying, creating, and modifying tasks with optional subtask arrays in a single call, as well as managing personal todos.
• Active Async Memory (Context Cache): Prefetches and caches your profile and project contexts, refreshing asynchronously in the background every 60 seconds. Dynamic context details are injected directly into tool definitions for instant availability without extra roundtrips.
• API Actions Draft Safety Shield: Intercepts write requests (POST, PATCH, DELETE) made via external API keys. Changes are logged as drafts and returned as 202 Accepted for human review and manual approval inside the web application, keeping your workspace secure.
• Secure Stdio Communication: Operates over standard input/output (stdio), avoiding firewall, routing, or open-port complexities.

🛠️ Configuration & Installation

Step 1: Generate your API Token

1. Log in to your hosted ManageMate instance (e.g., https://<base-url> or http://localhost:5173).
2. Navigate to your Account Settings (Profile Page).
3. Scroll down to the API Keys & MCP Integration section and click + Add Token.
4. Set a descriptive name (e.g., "Claude Desktop"), choose your scopes/permissions, restrict the token to specific projects (optional), and click Generate Token.
5. Copy the token immediately (starts with mm_pat_). For security, it will never be shown again!

Step 2: Register the Server in Your AI Client

1. Claude Desktop

Add the server configuration to your Claude Desktop settings file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "managemate": {
      "command": "npx",
      "args": ["-y", "@jayakrishna007/managemate-mcp-server"],
      "env": {
        "MANAGEMATE_API_URL": "https://<base-url>/api",
        "MANAGEMATE_API_TOKEN": "${MANAGEMATE_API_TOKEN}"
      }
    }
  }
}

2. Cursor IDE

1. Go to Cursor Settings -> Features -> MCP.
2. Click + Add New MCP Server.
3. Fill in the fields:
   • Name: ManageMates
   • Type: command
   • Command: npx -y @jayakrishna007/managemate-mcp-server
4. Add the following environment variables in the setup window:
   • Key: MANAGEMATE_API_URL / Value: https://<base-url>/api
   • Key: MANAGEMATE_API_TOKEN / Value: ${MANAGEMATE_API_TOKEN}

🌐 Environment Variables

| Variable | Required | Default | Description | | ---------------------- | -------- | ------------------------ | ----------------------------------------------- | | MANAGEMATE_API_TOKEN | Yes | — | Your personal API token starting with mm_pat_ | | MANAGEMATE_API_URL | No | https://<base-url>/api | The base URL of your hosted ManageMate backend |

🧰 Exposed Tools & Capabilities

The server registers the following secure tools with your AI agent:

1. list_projects

Retrieve all projects assigned to or managed by you (subject to token project restrictions).

• Inputs: None

2. get_project_details

Get detailed information about a specific project, including its list of modules.

• Inputs:
  • id (string, required): The UUID of the project.

3. list_tasks

Query and filter tasks in your workspace with built-in native pagination and advanced filtering.

• Inputs:
  • projectId (string, optional): Filter tasks by Project UUID.
  • moduleId (string, optional): Filter tasks by Module UUID.
  • status (string, optional): "BACKLOG", "TODO", "IN_PROGRESS", "REVIEW", "DONE".
  • priority (string, optional): "LOW", "MEDIUM", "HIGH", "URGENT".
  • onlyMyTasks (boolean, optional): Restricts tasks to those assigned to or reviewed by you. (default: true).
  • activeOnly (boolean, optional): Filter to retrieve only unresolved tasks ("TODO", "IN_PROGRESS", "REVIEW").
  • deadlineDate (string, optional): Match tasks having a specific deadline date (e.g., YYYY-MM-DD).
  • page (number, optional): Page number for offset pagination (default: 1).
  • limit (number, optional): Number of tasks per page (default: 10).

4. create_task

Create a new task under a module. Optionally include subtasks with deadlines in a single call.

• Inputs:
  • moduleId (string, required): The UUID of the module to add the task to.
  • title (string, required): The task title.
  • description (string, optional): Detailed description.
  • assigneeId (string, optional): UUID of the user assigned to this task.
  • reviewerId (string, optional): UUID of the user reviewing this task (required if status is REVIEW).
  • deadlineAt (string, optional): ISO date string for task deadline.
  • priority (string, optional): "LOW", "MEDIUM", "HIGH", "URGENT" (default: "MEDIUM").
  • status (string, optional): "BACKLOG", "TODO", "IN_PROGRESS", "REVIEW", "DONE" (default: "TODO").
  • category (string, optional): Optional category/tag (e.g., "Frontend", "Bug").
  • subTasks (array, optional): List of objects (containing title and optional deadlineAt ISO date) to instantiate as subtasks in a single call.

5. update_task

Edit an existing task (e.g., modify status, assignee, priority, description, or notes).

• Inputs:
  • id (string, required): The UUID of the task to update.
  • title, description, assigneeId, reviewerId, deadlineAt, status, priority, remark (all optional).

6. list_todos

Fetch your personal ManageMate scratchpad todos.

• Inputs: None

7. create_todo

Add a new personal todo item, optionally linking it to an active task.

• Inputs:
  • note (string, required): The note content.
  • taskId (string, optional): Optional UUID of an active task to link this todo to.

8. get_active_context

Inspect the current cached active context details (current user, projects, last activity) asynchronously managed by the server.

• Inputs: None

9. refresh_active_context

Force an immediate manual backend refresh of the context cache.

• Inputs: None

💻 Local Development & Debugging

If you are developing or testing this package locally:

1. Build and Link Globally

# Link globally on your machine using Bun
cd apps/mcp-server
bun link

2. Configure Local IDE to target Local Index

Rather than fetching from npm, configure your client mcp.json to target node with your local absolute path:

"managemate-local": {
  "command": "node",
  "args": ["/absolute/path/to/ManageMate/apps/mcp-server/index.js"],
  "env": {
    "MANAGEMATE_API_URL": "http://localhost:5000/api",
    "MANAGEMATE_API_TOKEN": "mm_pat_your_local_generated_token_here"
  }
}

3. Use the MCP Inspector

We highly recommend debugging tool schemas and responses using the official MCP Inspector:

export MANAGEMATE_API_URL="http://localhost:5000/api"
export MANAGEMATE_API_TOKEN="your_local_token"
npx @modelcontextprotocol/inspector node index.js

📦 Publishing Updates to npm

Follow these simple steps to release updates to the public registry:

1. Verify your credentials:

   npm login

2. Increment the version:

   Update the "version" field in package.json appropriately (e.g., 1.0.1).

3. Publish to registry:

   Because this is a scoped package (@jayakrishna007), you must publish it with public access parameters:

   npm publish --access public

📄 License

This project is licensed under the MIT License. See LICENSE for details.