# taskflow-mcp
**AI-powered Notion task workflow automation for Claude Code**
taskflow-mcp is a Model Context Protocol (MCP) server that automates Notion task workflows with AI-powered tag processing. Simply add MCP tags to your Notion tasks, and Claude Code will intelligently interrogate, expand, critique, rewrite, and even implement them.
---
## 🎯 Features
### Full MCP Implementation
- **4 Tools** - Direct task processing, querying, and updates
- **3 Resources** - Quick access to Ready, In Progress, and all tagged tasks
- **6 Prompts** - AI-powered workflows (interrogate, expand, critique, user stories, rewrite, prepare for coding)
- **Sampling** - LLM-powered analysis integrated via prompts
### Intelligent Tag Processing
- **Priority-based** - Tags processed in optimal order automatically
- **Persona support** - "think like X" tags add expert context to all analysis
- **Automatic tag removal** - Tags cleared after successful processing
- **Dry-run mode** - Preview what would happen without making changes
### AI-Powered Workflows (with Automatic Actions)
- **interrogate** - Claude asks clarifying questions → **Saves as comment**
- **expand** - Adds technical detail, APIs, edge cases → **Saves as comment**
- **rewrite** - Rewrites task for clarity → **Updates task description**
- **estimate** - Estimates effort and refactoring → **Saves as comment**
- **critique** - Provides constructive feedback → **Saves as comment**
- **user stories** - Generates user stories → **Appends to description**
- **to-do** - Adds to todo list → **No code written**
- **code** - **Actually implements the feature (WRITES CODE)**
- **confirm** - Verifies implementation complete → **Saves verification as comment**
---
## 🚀 Quick Start
### 1. Install
```bash
git clone https://github.com/themightyboosh/taskflow-mcp.git
cd taskflow-mcp
pnpm install
```
### 2. Configure
Create `.env` file in your project directory:
```env
NOTION_TOKEN=ntn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NOTION_DATABASE_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
**Get your Notion token:** https://www.notion.so/my-integrations
### 3. Setup Claude Code
Add to your `.mcp.json` (or Claude Code config):
```json
{
"mcpServers": {
"taskflow-mcp": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/taskflow-mcp/packages/mcp/index.js"]
}
}
}
```
### 4. Add MCP Tags in Notion
Add a multi-select property called **"MCP"** to your Notion database, then tag tasks with:
- **think like [persona]** - e.g., "think like a security engineer"
- **interrogate** - Claude asks clarifying questions
- **expand** - Add technical detail
- **rewrite** - Rewrite for clarity
- **critique** - Get constructive feedback
- **user stories** - Generate user stories
- **to-do** - Add to todo list only
- **code** - Implement the task automatically
### 5. Use in Claude Code
**Via Resources:**
```
Show me notion://tasks/ready
```
**Via Tools:**
```
Process all my Notion tasks
```
**Via Prompts:**
```
Interrogate task [task-id]
```
---
## 📖 Documentation
- **[SETUP.md](./SETUP.md)** - Detailed setup guide
- **[MCP_CAPABILITIES.md](./MCP_CAPABILITIES.md)** - Full MCP capability reference
---
## 🏗️ Architecture
```
taskflow-mcp/
├── packages/mcp/
│ ├── index.js # Main MCP server
│ ├── notion-client.js # Notion API wrapper
│ ├── utils/
│ │ ├── config-loader.js # Per-project .env loading
│ │ ├── tag-manager.js # Tag priority & processing
│ │ └── image-downloader.js # Image download for vision
├── .env.example
├── .mcp.json.example
└── README.md
```
---
## 🎨 Tag Processing Order
Tags are processed in this priority order:
1. **think like [X]** - Sets persona context for all subsequent processing
2. **interrogate** - Asks clarifying questions
3. **rewrite** - Rewrites description for clarity
4. **estimate** - Estimates level of effort and refactoring needs
5. **expand** - Adds technical detail
6. **critique** - Provides feedback (with persona if set)
7. **user stories** - Generates user stories (appended to task description)
8. **to-do** - Adds to todo list (no implementation)
9. **code** - Triggers implementation (ONLY tag that writes code)
10. **confirm** - Verifies implementation is complete
Each tag is removed after successful processing.
---
## 💡 Usage Examples
### Example 1: Requirements Gathering
**Notion Task:** "Add user authentication"
**MCP Tags:** `interrogate`, `expand`, `user stories`
**What happens:**
1. **interrogate** → Claude asks questions about auth method, session management → **Saves as comment**
2. **expand** → Adds technical detail (JWT vs session, password requirements) → **Saves as comment**
3. **user stories** → Generates user stories for different auth scenarios → **Appends to task description**
4. All three tags removed after processing
5. All actions performed automatically - no manual intervention needed
### Example 2: Expert Review
**Notion Task:** "Implement payment processing"
**MCP Tags:** `think like a security engineer`, `critique`, `expand`
**What happens:**
1. **think like** → Sets persona: "security engineer"
2. **critique** → Critiques from security perspective (PCI compliance, data protection) → **Saves as comment**
3. **expand** → Expands with security-focused technical details → **Saves as comment**
4. All tags removed
5. All comments automatically added to Notion task
### Example 3: Full Implementation
**Notion Task:** "Add dark mode toggle"
**MCP Tags:** `interrogate`, `expand`, `code`
**What happens:**
1. **interrogate** → Claude asks about implementation approach, storage → **Saves as comment**
2. **expand** → Adds technical detail (CSS variables, localStorage, toggle component) → **Saves as comment**
3. **code** → Reviews requirements → **WRITES THE ACTUAL CODE** (creates files, edits components, etc.)
4. All tags removed after processing
5. Feature is fully implemented - not just analyzed
---
## 🔧 MCP Capabilities
### Tools (4)
| Tool | Description |
|------|-------------|
| `process_tasks` | Process all tasks with MCP tags |
| `query_tasks` | Query tasks by status or MCP tags |
| `add_comment` | Add comment to Notion task |
| `update_task` | Update task properties |
### Resources (3)
| Resource | Description |
|----------|-------------|
| `notion://tasks/ready` | Ready tasks with MCP tags |
| `notion://tasks/in-progress` | In Progress tasks with MCP tags |
| `notion://tasks/with-mcp-tags` | All tasks with MCP tags |
### Prompts (6)
| Prompt | Description |
|--------|-------------|
| `interrogate_task` | Ask clarifying questions |
| `expand_task` | Add technical detail |
| `critique_task` | Provide constructive feedback |
| `generate_user_stories` | Generate user stories |
| `rewrite_task` | Rewrite for clarity |
| `prepare_for_coding` | Analyze and implement |
See [MCP_CAPABILITIES.md](./MCP_CAPABILITIES.md) for full details.
---
## 🛠️ Development
```bash
# Install dependencies
pnpm install
# Start MCP server (for testing)
pnpm start
# Development mode (auto-reload)
pnpm dev
```
---
## 🐛 Troubleshooting
### "No .env file found"
- taskflow-mcp requires per-project `.env` file
- Run from directory containing `.env` with `NOTION_TOKEN` and `NOTION_DATABASE_ID`
### "Property MCP does not exist"
- Add a multi-select property called "MCP" to your Notion database
- Configure your Notion integration to have access to the database
### MCP server not connecting
- Verify absolute path in `.mcp.json` is correct
- Ensure Node.js 20+ is installed
- Check Notion token is valid
- Restart Claude Code after config changes
---
## 📝 Requirements
- **Node.js** 20+
- **pnpm** 10+ (or npm)
- **Notion integration** with database access
- **Claude Code** with MCP support
---
## 🤝 Contributing
Contributions welcome! Please open an issue or PR.
### Development Setup
1. Fork and clone
2. `pnpm install`
3. Create a branch: `git checkout -b feat/my-feature`
4. Make changes and test
5. Commit: `git commit -m "feat: add my feature"`
6. Push: `git push origin feat/my-feature`
7. Open a PR
---
## 📧 Support
- **Issues**: [GitHub Issues](https://github.com/themightyboosh/taskflow-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/themightyboosh/taskflow-mcp/discussions)
---
## 📜 License
MIT © Monumental
---
## 🎯 Roadmap
- [ ] Multiple database support
- [ ] Custom tag definitions via config
- [ ] Background polling mode (watch for new tags)
- [ ] Webhook support for real-time processing
- [ ] Analytics dashboard
- [ ] Slack/Discord notifications
- [ ] Task templates
- [ ] Batch operations
---
**Made with ❤️ by Monumental**
