| Name | agile-mcp-server JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | None |
| Summary | An Agile Project Management MCP Server that transforms LLMs into powerful agile assistants |
| upload_time | 2025-07-09 11:10:48 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
agile
kanban
llm
mcp
project-management
scrum
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Agile MCP Server
Transform Large Language Models into powerful agile project management assistants through the Model Context Protocol (MCP).
## Overview
The Agile MCP Server provides a comprehensive set of tools for agile project management, including user story creation, sprint planning, progress tracking, and team coordination. It integrates seamlessly with MCP-compatible clients like Claude Desktop and Cursor to bring agile workflows directly into your development environment.
## Why Agile MCP?
- **Empower LLMs**: Turn your LLM into a proactive agile assistant, capable of managing projects, tracking progress, and guiding development workflows.
- **Local & Private**: All your project data is stored locally, ensuring privacy and control.
- **Seamless Integration**: Works with any MCP-compatible client, embedding agile practices directly into your existing development tools.
- **Type-Safe & Robust**: Built with Pydantic for robust data models and type-safe operations, ensuring reliability and maintainability.
## Features
- **User Story Management**: Create, update, and track user stories with priorities, points, and tags
- **Sprint Planning**: Organize stories into time-boxed sprints with goals and timelines
- **Progress Tracking**: Monitor sprint progress, story completion, and team velocity
- **MCP Integration**: Works with any MCP-compatible client for seamless workflow integration
- **Local Storage**: All data stored locally in your project directory
- **Type-Safe**: Full TypeScript support with proper parameter validation
## Quick Start
### Installation
To get started with the Agile MCP Server, clone the repository and install dependencies:
```bash
git clone <repository-url>
cd agile_mcp
uv sync
```
### Running the Server
You can run the server with your project directory:
```bash
uv run python -m agile_mcp --project .
uv run python -m agile_mcp --project .
# Or start without project (set later using tools)
uv run python -m agile_mcp
```
### MCP Client Integration
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"agile-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "agile_mcp", "--project", "/path/to/your/project"],
"cwd": "/path/to/agile-mcp"
}
}
}
```
## Documentation
- **[User Guide](docs/USER_GUIDE.md)** - Comprehensive guide for getting started and daily workflows
- **[API Reference](docs/API_REFERENCE.md)** - Complete documentation of all MCP tools and parameters
- **[Examples](examples/)** - Code examples and usage demonstrations
## Available Tools
### Project Management
- `set_project` - Set the project directory
- `get_project` - Get the current project directory
### User Story Management
- `create_story` - Create a new user story
- `get_story` - Retrieve a story by ID
- `update_story` - Update an existing story
- `list_stories` - List stories with optional filtering
- `delete_story` - Delete a story
### Sprint Management
- `create_sprint` - Create a new sprint
- `get_sprint` - Retrieve a sprint by ID
- `list_sprints` - List sprints with optional filtering
- `update_sprint` - Update an existing sprint
- `manage_sprint_stories` - Add/remove stories from sprints
- `get_sprint_progress` - Get detailed sprint progress
- `get_active_sprint` - Get the currently active sprint
## Project Structure
```
agile_mcp/
├── src/agile_mcp/ # Main source code
│ ├── models/ # Data models (Story, Sprint, etc.)
│ ├── services/ # Business logic services
│ ├── storage/ # File system storage layer
│ ├── tools/ # MCP tool implementations
│ └── server.py # Main MCP server
├── docs/ # Documentation
│ ├── API_REFERENCE.md # Complete API documentation
│ └── USER_GUIDE.md # User guide and workflows
├── examples/ # Usage examples
├── tests/ # Test suite
└── README.md # This file
```
## Development
### Requirements
- Python 3.10+
- uv (for package management)
### Setup Development Environment
```bash
# Install dependencies including dev tools
uv sync
# For development, you can also install the package in editable mode
# This allows you to run examples and tools without full path specifications
uv pip install -e .
# Run tests (includes coverage reporting by default)
uv run pytest
# Run tests with verbose coverage report
uv run pytest -v
# Run tests without coverage (for faster execution)
uv run pytest --no-cov
# Type checking
uv run mypy src/
# Code formatting
uv run ruff format src/ tests/
uv run ruff check src/ tests/
```
### Running Examples
The example scripts demonstrate best practices for using the Agile MCP Server and can be run after setting up the development environment:
```bash
# Option 1: Using uv run (recommended for development)
uv run python examples/basic_usage_demo.py
uv run python examples/sprint_demo.py
# Option 2: After editable installation (alternative)
python examples/basic_usage_demo.py
python examples/sprint_demo.py
```
The examples demonstrate:
- **`basic_usage_demo.py`**: Core functionality including story creation, listing, and updates
- **`sprint_demo.py`**: Complete sprint workflow from creation to completion
Both examples use proper JSON parsing patterns that mirror how real MCP clients handle tool responses, making them excellent references for integration work.
### Test Coverage
The project maintains a minimum test coverage of 75%. Coverage reports are automatically generated when running tests:
- **Terminal Report**: Shows missing lines for each file
- **HTML Report**: Detailed interactive report in `htmlcov/` directory
- **Coverage Threshold**: Tests will fail if coverage drops below 75%
View the HTML coverage report by opening `htmlcov/index.html` in your browser after running tests.
### Transport Options
The server supports multiple transport protocols:
```bash
# STDIO transport (default) - for direct LLM integration
uv run python -m agile_mcp --project . --transport stdio
# SSE transport - for web-based clients
uv run python -m agile_mcp --project . --transport sse --host 0.0.0.0 --port 8000
```
### Project Directory Management
Start the server without a project directory and set it later using the `set_project` tool via your LLM client.
## Examples
### Basic Workflow
```python
# 1. Set up project
set_project(project_path=".")
# 2. Create a user story
create_story(
title="User Authentication",
description="Implement secure login system",
priority="high",
tags="authentication, security"
)
# 3. Create a sprint
create_sprint(
name="Sprint 1 - Foundation",
goal="Establish core functionality",
start_date="2025-01-07",
end_date="2025-01-21"
)
# 4. Add story to sprint
manage_sprint_stories(
sprint_id="SPRINT-123",
action="add",
story_id="STORY-456"
)
# 5. Start the sprint
update_sprint(sprint_id="SPRINT-123", status="active")
```
See the [examples directory](examples/) for more detailed usage examples.
## Architecture
The Agile MCP Server follows a clean architecture pattern:
- **Tools Layer**: MCP-compatible tool interfaces
- **Services Layer**: Business logic and workflow management
- **Storage Layer**: File-based persistence with JSON storage
- **Models Layer**: Type-safe data models with Pydantic
All data is stored locally in a `.agile` directory within your project, ensuring full control and privacy of your project data.
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following the coding standards
4. Add tests for new functionality
5. Ensure all tests pass (`uv run pytest`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- Built on the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) standard
- Inspired by agile development practices and tools
- Uses [FastMCP](https://github.com/jlowin/fastmcp) for MCP server implementation
Raw data
{
"_id": null,
"home_page": null,
"name": "agile-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agile, kanban, llm, mcp, project-management, scrum",
"author": null,
"author_email": "Agile MCP Team <team@agile-mcp.com>",
"download_url": "https://files.pythonhosted.org/packages/94/2d/7dabe2775be1715245c570b38ff5ec3a05725b1a937398dc99930868ee66/agile_mcp_server-0.4.0.tar.gz",
"platform": null,
"description": "# Agile MCP Server\n\nTransform Large Language Models into powerful agile project management assistants through the Model Context Protocol (MCP).\n\n## Overview\n\nThe Agile MCP Server provides a comprehensive set of tools for agile project management, including user story creation, sprint planning, progress tracking, and team coordination. It integrates seamlessly with MCP-compatible clients like Claude Desktop and Cursor to bring agile workflows directly into your development environment.\n\n## Why Agile MCP?\n\n- **Empower LLMs**: Turn your LLM into a proactive agile assistant, capable of managing projects, tracking progress, and guiding development workflows.\n- **Local & Private**: All your project data is stored locally, ensuring privacy and control.\n- **Seamless Integration**: Works with any MCP-compatible client, embedding agile practices directly into your existing development tools.\n- **Type-Safe & Robust**: Built with Pydantic for robust data models and type-safe operations, ensuring reliability and maintainability.\n\n## Features\n\n- **User Story Management**: Create, update, and track user stories with priorities, points, and tags\n- **Sprint Planning**: Organize stories into time-boxed sprints with goals and timelines\n- **Progress Tracking**: Monitor sprint progress, story completion, and team velocity\n- **MCP Integration**: Works with any MCP-compatible client for seamless workflow integration\n- **Local Storage**: All data stored locally in your project directory\n- **Type-Safe**: Full TypeScript support with proper parameter validation\n\n## Quick Start\n\n### Installation\n\nTo get started with the Agile MCP Server, clone the repository and install dependencies:\n\n```bash\ngit clone <repository-url>\ncd agile_mcp\nuv sync\n```\n\n### Running the Server\n\nYou can run the server with your project directory:\n\n```bash\nuv run python -m agile_mcp --project .\nuv run python -m agile_mcp --project .\n\n# Or start without project (set later using tools)\nuv run python -m agile_mcp\n```\n\n### MCP Client Integration\n\nAdd to your Claude Desktop configuration:\n\n```json\n{\n \"mcpServers\": {\n \"agile-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"-m\", \"agile_mcp\", \"--project\", \"/path/to/your/project\"],\n \"cwd\": \"/path/to/agile-mcp\"\n }\n }\n}\n```\n\n## Documentation\n\n- **[User Guide](docs/USER_GUIDE.md)** - Comprehensive guide for getting started and daily workflows\n- **[API Reference](docs/API_REFERENCE.md)** - Complete documentation of all MCP tools and parameters\n- **[Examples](examples/)** - Code examples and usage demonstrations\n\n## Available Tools\n\n### Project Management\n- `set_project` - Set the project directory\n- `get_project` - Get the current project directory\n\n### User Story Management\n- `create_story` - Create a new user story\n- `get_story` - Retrieve a story by ID\n- `update_story` - Update an existing story\n- `list_stories` - List stories with optional filtering\n- `delete_story` - Delete a story\n\n### Sprint Management\n- `create_sprint` - Create a new sprint\n- `get_sprint` - Retrieve a sprint by ID\n- `list_sprints` - List sprints with optional filtering\n- `update_sprint` - Update an existing sprint\n- `manage_sprint_stories` - Add/remove stories from sprints\n- `get_sprint_progress` - Get detailed sprint progress\n- `get_active_sprint` - Get the currently active sprint\n\n## Project Structure\n\n```\nagile_mcp/\n\u251c\u2500\u2500 src/agile_mcp/ # Main source code\n\u2502 \u251c\u2500\u2500 models/ # Data models (Story, Sprint, etc.)\n\u2502 \u251c\u2500\u2500 services/ # Business logic services\n\u2502 \u251c\u2500\u2500 storage/ # File system storage layer\n\u2502 \u251c\u2500\u2500 tools/ # MCP tool implementations\n\u2502 \u2514\u2500\u2500 server.py # Main MCP server\n\u251c\u2500\u2500 docs/ # Documentation\n\u2502 \u251c\u2500\u2500 API_REFERENCE.md # Complete API documentation\n\u2502 \u2514\u2500\u2500 USER_GUIDE.md # User guide and workflows\n\u251c\u2500\u2500 examples/ # Usage examples\n\u251c\u2500\u2500 tests/ # Test suite\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Development\n\n### Requirements\n\n- Python 3.10+\n- uv (for package management)\n\n### Setup Development Environment\n\n```bash\n# Install dependencies including dev tools\nuv sync\n\n# For development, you can also install the package in editable mode\n# This allows you to run examples and tools without full path specifications\nuv pip install -e .\n\n# Run tests (includes coverage reporting by default)\nuv run pytest\n\n# Run tests with verbose coverage report\nuv run pytest -v\n\n# Run tests without coverage (for faster execution)\nuv run pytest --no-cov\n\n# Type checking\nuv run mypy src/\n\n# Code formatting\nuv run ruff format src/ tests/\nuv run ruff check src/ tests/\n```\n\n### Running Examples\n\nThe example scripts demonstrate best practices for using the Agile MCP Server and can be run after setting up the development environment:\n\n```bash\n# Option 1: Using uv run (recommended for development)\nuv run python examples/basic_usage_demo.py\nuv run python examples/sprint_demo.py\n\n# Option 2: After editable installation (alternative)\npython examples/basic_usage_demo.py\npython examples/sprint_demo.py\n```\n\nThe examples demonstrate:\n- **`basic_usage_demo.py`**: Core functionality including story creation, listing, and updates\n- **`sprint_demo.py`**: Complete sprint workflow from creation to completion\n\nBoth examples use proper JSON parsing patterns that mirror how real MCP clients handle tool responses, making them excellent references for integration work.\n\n### Test Coverage\n\nThe project maintains a minimum test coverage of 75%. Coverage reports are automatically generated when running tests:\n\n- **Terminal Report**: Shows missing lines for each file\n- **HTML Report**: Detailed interactive report in `htmlcov/` directory\n- **Coverage Threshold**: Tests will fail if coverage drops below 75%\n\nView the HTML coverage report by opening `htmlcov/index.html` in your browser after running tests.\n\n### Transport Options\n\nThe server supports multiple transport protocols:\n\n```bash\n# STDIO transport (default) - for direct LLM integration\nuv run python -m agile_mcp --project . --transport stdio\n\n# SSE transport - for web-based clients\nuv run python -m agile_mcp --project . --transport sse --host 0.0.0.0 --port 8000\n```\n\n### Project Directory Management\n\nStart the server without a project directory and set it later using the `set_project` tool via your LLM client.\n\n## Examples\n\n### Basic Workflow\n\n```python\n# 1. Set up project\nset_project(project_path=\".\")\n\n# 2. Create a user story\ncreate_story(\n title=\"User Authentication\",\n description=\"Implement secure login system\",\n priority=\"high\",\n tags=\"authentication, security\"\n)\n\n# 3. Create a sprint\ncreate_sprint(\n name=\"Sprint 1 - Foundation\",\n goal=\"Establish core functionality\",\n start_date=\"2025-01-07\",\n end_date=\"2025-01-21\"\n)\n\n# 4. Add story to sprint\nmanage_sprint_stories(\n sprint_id=\"SPRINT-123\",\n action=\"add\",\n story_id=\"STORY-456\"\n)\n\n# 5. Start the sprint\nupdate_sprint(sprint_id=\"SPRINT-123\", status=\"active\")\n```\n\nSee the [examples directory](examples/) for more detailed usage examples.\n\n## Architecture\n\nThe Agile MCP Server follows a clean architecture pattern:\n\n- **Tools Layer**: MCP-compatible tool interfaces\n- **Services Layer**: Business logic and workflow management\n- **Storage Layer**: File-based persistence with JSON storage\n- **Models Layer**: Type-safe data models with Pydantic\n\nAll data is stored locally in a `.agile` directory within your project, ensuring full control and privacy of your project data.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes following the coding standards\n4. Add tests for new functionality\n5. Ensure all tests pass (`uv run pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Built on the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) standard\n- Inspired by agile development practices and tools\n- Uses [FastMCP](https://github.com/jlowin/fastmcp) for MCP server implementation\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An Agile Project Management MCP Server that transforms LLMs into powerful agile assistants",
"version": "0.4.0",
"project_urls": {
"Bug Tracker": "https://github.com/agile-mcp/agile-mcp-server/issues",
"Documentation": "https://agile-mcp.readthedocs.io/",
"Homepage": "https://github.com/agile-mcp/agile-mcp-server",
"Repository": "https://github.com/agile-mcp/agile-mcp-server"
},
"split_keywords": [
"agile",
" kanban",
" llm",
" mcp",
" project-management",
" scrum"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eafe69d05f4873468f14290ace9dd4322a19608ae128d47116761b45315e6286",
"md5": "524bd5590507fbd628313da3db2e9ce4",
"sha256": "35b30f409286a67f87b18c747d86c226848b182576dd3403fd4dac49fad1219a"
},
"downloads": -1,
"filename": "agile_mcp_server-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "524bd5590507fbd628313da3db2e9ce4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 75164,
"upload_time": "2025-07-09T11:10:46",
"upload_time_iso_8601": "2025-07-09T11:10:46.803189Z",
"url": "https://files.pythonhosted.org/packages/ea/fe/69d05f4873468f14290ace9dd4322a19608ae128d47116761b45315e6286/agile_mcp_server-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "942d7dabe2775be1715245c570b38ff5ec3a05725b1a937398dc99930868ee66",
"md5": "7dceff9d59dc7e373af84d306d9454cd",
"sha256": "c2ec11706d3cd57fba7b735b2bf1216e060bd88b78fec4e0e7f0b3b9272ea128"
},
"downloads": -1,
"filename": "agile_mcp_server-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "7dceff9d59dc7e373af84d306d9454cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 170614,
"upload_time": "2025-07-09T11:10:48",
"upload_time_iso_8601": "2025-07-09T11:10:48.416148Z",
"url": "https://files.pythonhosted.org/packages/94/2d/7dabe2775be1715245c570b38ff5ec3a05725b1a937398dc99930868ee66/agile_mcp_server-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 11:10:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "agile-mcp",
"github_project": "agile-mcp-server",
"github_not_found": true,
"lcname": "agile-mcp-server"
}
