soapko/alice-mcp-server

Alice MCP - Lightweight Agile Task Management

Alice is a lightweight, local task management system designed for AI coding environments using the Model Context Protocol (MCP). It provides comprehensive project management capabilities with bulk operations, dynamic planning, and architectural decision tracking - all running locally on your machine with complete project isolation.

Optimized for Cline and other AI coding assistants, Alice transforms how you manage development workflows with intelligent automation and comprehensive tracking.

See the Documentation section for detailed guides and the Quick Start for Cline for immediate setup.

Key Features

🚀 Efficient Bulk Operations

• Bulk Task Management: Create and update multiple tasks simultaneously
• Bulk Decision Records: Batch process architectural decisions with rich markdown support
• Atomic Operations: All-or-nothing processing with comprehensive error reporting

📊 Intelligent Project Management

• Project Isolation: All data scoped to specific projects with secure separation
• Dynamic Project Planning: AI-queryable prioritized backlogs that adapt to progress
• Task & Epic Tracking: Hierarchical organization with status history tracking
• Message Logging: Contextual notes and discussions tied to specific tasks

🏗️ Architectural Decision Records (ADR)

• Structured Decision Tracking: Document context, decisions, and consequences
• Markdown-Rich Content: Full formatting support for complex technical documentation
• Task Integration: Link decisions to the tasks that prompted them
• Queryable History: Maintain institutional knowledge across development cycles

🔧 Developer Experience

• Cline-Optimized: Seamless integration with automatic server management
• Local-First: Runs entirely on your machine using SQLite - no external dependencies
• MCP Native: Built specifically for Model Context Protocol environments
• Comprehensive Testing: 62 tests ensuring reliability and stability

Quick Start for Cline Users

The fastest way to get Alice running with Cline:

1. Clone and Setup:

   git clone https://github.com/your-organization/alice-mcp.git
   cd alice-mcp
   python -m venv alice-env
   source alice-env/bin/activate  # On Windows: alice-env\Scripts\activate
   pip install -r requirements.txt
   

2. Automated MCP Setup:

   ./scripts/setup-alice-mcp.sh
   

   This single command handles everything: creates the MCP server, installs dependencies, builds the TypeScript, and updates your Cline settings.

3. Restart Cline and test with:

   Use alice to create a project named "test-project"
   

That's it! Alice is now integrated with Cline and ready for efficient project management.

Advanced Setup

For manual setup or customization:

1. Clone the repository:

   git clone https://github.com/your-organization/alice-mcp.git
   cd alice-mcp
   

2. Create and activate a Python virtual environment:

   # Create the environment
   python -m venv alice-env
   
   # Activate it (Linux/macOS)
   source alice-env/bin/activate
   
   # Activate it (Windows)
   # alice-env\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

For detailed manual setup instructions, see .

Running the Server

Automatic Startup (MCP Integration)

When used with an MCP-compatible environment, Alice starts automatically - both the FastAPI backend and the MCP server components launch together. This is handled by the scripts/start-alice-servers.sh wrapper script, which:

• Activates the Python environment
• Installs dependencies
• Starts the FastAPI server
• Starts the MCP server

Manual Startup (Development)

If you need to run the server manually (for development or testing), you can:

1. Start the FastAPI server:

   uvicorn app.main:app --reload
   

   The server will be available at http://127.0.0.1:8000

2. For debugging issues, you can run the wrapper script directly:

   /bin/zsh scripts/start-alice-servers.sh --debug
   

Getting Started

1. Start the server (see above).
2. Create a project: Send a POST request to /projects/ with a unique project name.

   { "name": "my-new-project" }
   

3. Identify your project: For interacting with tasks, epics, and messages via the Alice MCP server tools, you will use the project's name (e.g., "my-new-project") as the project_id argument. The MCP server handles the translation to the internal numeric ID required by the API.
4. API Endpoints (Direct API Usage): If interacting directly with the FastAPI backend (not through the MCP server), all subsequent operations for tasks, epics, and messages require the internal numeric project_id in the URL path (e.g., /{numeric_project_id}/tasks/). You can find this numeric ID by listing projects (GET /projects/) or getting by name (GET /projects/by-name/my-new-project).

Project Isolation API Structure

Alice's FastAPI backend uses numeric project IDs in the URL path to ensure data isolation. However, when using the Alice MCP server tools, you should provide the project's name (string) as the project_id argument. The MCP server will resolve this to the correct numeric ID for the API.

Direct API examples:

• Project Management: /projects/ (e.g., POST /projects/, GET /projects/{project_id})
• Tasks: /{numeric_project_id}/tasks/ (e.g., POST /1/tasks/, GET /1/tasks/{task_id})
• Epics: /{numeric_project_id}/epics/ (e.g., POST /1/epics/, GET /1/epics/{epic_id})
• Messages: /{numeric_project_id}/tasks/{task_id}/messages/ (e.g., POST /1/tasks/5/messages/)

Replace 1 with the actual internal numeric project_id when using the API directly.

Powerful New Features

Alice has been upgraded with powerful new features to enhance your development workflow, ensuring that context and priority are never lost between coding sessions.

Dynamic Project Planning

Tired of project plans becoming stale in static documents? Alice introduces a dynamic, queryable project plan.

• Create a Prioritized Backlog: Use the update_priority_plan tool to set the exact order of tasks to be worked on. You can provide a rationale for each task's priority, giving essential context to your future self or other agents.
• Always Know What's Next: The get_next_task tool instantly returns the highest-priority task that isn't yet "Done" or "Canceled". This eliminates ambiguity and ensures focus is always on the most critical work.
• Live Status Updates: The project plan is always up-to-date. As tasks are completed, the plan automatically reflects their new status, providing a real-time view of progress.

Architectural Decision Records (ADR)

Capture the "why" behind your project's design with a structured, queryable log of architectural decisions.

• Document Key Decisions: Use the create_decision tool to record the context, decision, and consequences of important architectural choices.
• Preserve Context: New development threads can quickly get up to speed by reviewing past decisions, preventing the re-litigation of settled issues and ensuring consistency over time.
• Link to Tasks: Associate decisions with the specific tasks that prompted them, creating a clear audit trail of your project's evolution.

These features transform Alice from a simple task tracker into an intelligent partner that actively manages project context and priority, making your development process more efficient, transparent, and powerful.

Bulk Operations - Improved Efficiency

Alice's bulk operations deliver improved efficiency for development project management:

Bulk Task Operations:

• bulk_create_tasks: Create multiple tasks in a single operation with comprehensive validation
• bulk_update_tasks: Update multiple tasks simultaneously with atomic transaction guarantees

Bulk Decision Operations:

• bulk_create_decisions: Batch process architectural decisions with rich markdown support
• bulk_update_decisions: Update decision statuses and content across multiple records

Performance Benefits:

• Huge reduction in API calls compared to individual operations
• Atomic transactions with rollback protection ensure data consistency
• Detailed reporting shows success/failure status for each item

Example Usage:

// Create 5 tasks simultaneously
bulk_create_tasks("my-project", [
  { title: "Setup authentication", assignee: "Backend Team" },
  { title: "Design user interface", assignee: "Frontend Team" },
  { title: "Configure CI/CD pipeline", assignee: "DevOps Team" },
  { title: "Write API documentation", assignee: "Documentation Team" },
  { title: "Implement rate limiting", status: "In Progress" }
])

// Update multiple tasks with status changes
bulk_update_tasks("my-project", [
  { id: 1, update: { status: "Done" }},
  { id: 2, update: { status: "In Progress", assignee: "New Team" }},
  { id: 3, update: { description: "Updated requirements" }}
])

Running Tests

Ensure you have the virtual environment activated and dependencies installed. Then run:

pytest

API Documentation

While the server is running, you can access the interactive API documentation (provided by FastAPI) in your browser:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

Documentation

Detailed documentation can be found in the docs/ directory:

• : Covers architecture, features, and technical stack.
• : Detailed system, database, and API specifications.
• : Recommendations for integrating Alice with LLM custom instructions.

Contributing

Contributions are welcome! Please follow these guidelines:

• Adhere to the coding style (PEP 8, black, isort).
• Use type hints.
• Document public functions and APIs.
• Write unit tests for new features or bug fixes.
• Ensure all tests and linters pass before submitting changes.
• For significant changes, consider opening an issue first to discuss the approach.

Alice is certified by MCP Review. See its listing here: https://mcpreview.com/mcp-servers/soapko/alice-mcp-server