Metadata-Version: 2.4
Name: taskmajor
Version: 0.3.3
Summary: TaskMajor MCP. Coordinate your tasks. Execute with precision.
Requires-Python: <3.14,>=3.10
Requires-Dist: fastmcp<4.0.0,>=3.0.0
Requires-Dist: pydantic<3.0.0,>=2.8
Requires-Dist: pytaskwarrior<4.0.0,>=3.0.1
Requires-Dist: pyyaml<7.0.0,>=6.0.2
Provides-Extra: telemetry
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.39.1; extra == 'telemetry'
Requires-Dist: opentelemetry-instrumentation-httpx<1.0.0,>=0.60b1; extra == 'telemetry'
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.39.1; extra == 'telemetry'
Description-Content-Type: text/markdown

# TaskMajor — Tailored MCP Workflows for AI Agents

[![CI Tests](https://github.com/nschmeltz/taskmajor/workflows/CI/badge.svg)](https://github.com/nschmeltz/taskmajor/actions/workflows/ci.yml)
[![Coverage Status](https://img.shields.io/badge/coverage-90%25-brightgreen)](docs/TESTING.md#coverage)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet)](#mcp-model-context-protocol)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](#license)

> **Your tasks. Your method. Your agents.**

TaskMajor connects your AI assistants to your task management—organized your way, hosted on your terms.


Ask your assistant:
```
"Add a task to review the API spec"
"What's on my plate for today?"
"Run my daily review"
"Show me the roadmap for Project X"
```

## Why TaskMajor?
TaskWarrior is powerful but CLI-only. TaskMajor gives AI agents native access to its engine, and the profile system lets you shape the interaction model to match your methodology rather than the other way around.
Behind this sits [**TaskWarrior**](https://taskwarrior.org)—a remarkably flexible, battle-tested task engine. It runs locally, stores plain text, and bends to almost any organizational style. TaskMajor builds on that foundation and adds its own layer of adaptability: the **profile system**. Each profile defines a unique contract of exposed tools, views, and behaviors—turning TaskMajor into anything from a simple to-do list to a full GTD system or a multi-agent coordination hub. Explore the [built-in profiles](docs/user-guides/profiles/README.md) or learn how to compose and extend them in the [profile documentation](docs/user-guides/profiles/profile-system.md).

Ready to transform your task management? Jump straight into the [Quick Start](#quick-start) to get running in minutes.

## 🚀 Quick Start

```bash
pip install taskmajor
taskmajor
```

The server starts at `http://localhost:8888`. Point your AI agent at it.

> **That's it.** TaskMajor bundles an embedded TaskWarrior engine (no external TaskWarrior binary required).

---

**Go further:**

- 📦 **[Installation options](docs/getting-started/index.md)** — uv, Docker, from source
- ⚙️ **[Configuration & CLI](docs/CLI_USAGE.md)** — workspace dir (`-c`), config file, all flags
- 🎭 **[Profiles](docs/user-guides/profiles/README.md)** — GTD, project management, or your own workflow

  ```bash
  taskmajor --profile standard      # default: task CRUD + agenda
  taskmajor --profile productivity  # GTD: reviews, energy levels, contexts
  taskmajor --profile project-mgmt  # sprints, blockers, effort tracking
  ```


## 📚 Documentation

| Section | For |
|---------|-----|
| Agent configuration | Consult your agent's MCP documentation |
| **[Getting Started](docs/getting-started/index.md)** | DevOps / Deployment |
| **[API Reference](docs/api-reference/index.md)** | Developers / Integrators |
| **[Architecture](docs/developer/architecture.md)** | System design and concepts |
| **[Configuration](docs/getting-started/configuration.md)** | Environment variables and setup |
| **[Profiles](docs/user-guides/profiles/README.md)** | Workflow methodologies & custom profiles |
| **[Docker: Custom Profiles](docs/deployment/docker-custom-profile.md)** | Mount profiles without overwriting built-ins |
| **[Troubleshooting](https://github.com/nschmeltz/taskmajor/issues)** | Common issues and solutions |
| **[Contributing](docs/developer/contributing.md)** | Add a new agent integration |


## 🌐 Community

- **Issues & Features:** [GitHub Issues](https://github.com/nschmeltz/taskmajor/issues)
- **Discussions:** [GitHub Discussions](https://github.com/nschmeltz/taskmajor/discussions)

---

## 📄 License

MIT License — See [LICENSE](https://github.com/nschmeltz/taskmajor/blob/main/LICENSE) for details.

---

## 🏗 Acknowledgments

Built with:

- **[FastMCP](https://github.com/jlowin/fastmcp)** — Modern MCP framework
- **[pytaskwarrior](https://github.com/sznicolas/pytaskwarrior)** — Python bindings for TaskWarrior / TaskChampion
- **[taskchampion3-py-dev](https://pypi.org/project/taskchampion3-py-dev/)** — Embedded TaskChampion engine (PyO3/Rust, no external binary needed)
- **[Pydantic](https://docs.pydantic.dev/)** — Data validation
- **[OpenTelemetry](https://opentelemetry.io/)** — Observability

---
