# Follow Plan MCP Server
A comprehensive Model Context Protocol (MCP) server for intelligent project planning and task management with SQLite persistence and full-text search capabilities.
## Features
- **Task Management**: Create, update, and track tasks with status, priority, and progress
- **Feature Planning**: Manage user stories, epics, and feature specifications
- **Bug Tracking**: Report and track bugs with severity levels and reproduction steps
- **Rule Engine**: Define project rules, validations, and automation guidelines
- **Full-Text Search**: Advanced search across all plan items with relevance scoring
- **SQLite Storage**: Persistent storage with FTS5 full-text search indexing
- **Auto-Sync**: Automatic synchronization between database and filesystem
- **Backup/Restore**: Database backup and restore functionality
## Quick Start
### 1. Install Dependencies
```bash
npm install
```
### 2. Build the Project
```bash
npm run build
```
### 3. Start the MCP Server
```bash
npm start /path/to/your/project
```
The server will create a `.plan` directory in your project with the following structure:
```
.plan/
├── database.db # SQLite database
├── index.md # Project overview
├── tasks/ # Task files
├── features/ # Feature files
├── bugs/ # Bug files
├── rules/ # Rule files
├── workflows/ # Workflow documentation
├── changelog/ # Project changelog
└── tmp/ # Temporary files and logs
```
## MCP Tools
### Task Management
- `create_task` - Create a new task
- `update_task` - Update an existing task
- `get_task` - Get task details by ID
- `list_tasks` - List tasks with optional filters
- `delete_task` - Delete a task
### Feature Management
- `create_feature` - Create a new feature
- `update_feature` - Update an existing feature
- `get_feature` - Get feature details by ID
- `list_features` - List features with optional filters
- `delete_feature` - Delete a feature
### Bug Tracking
- `create_bug` - Create a new bug report
- `update_bug` - Update an existing bug
- `get_bug` - Get bug details by ID
- `list_bugs` - List bugs with optional filters
- `delete_bug` - Delete a bug
### Rule Management
- `create_rule` - Create a new project rule
- `update_rule` - Update an existing rule
- `get_rule` - Get rule details by ID
- `list_rules` - List rules with optional filters
- `delete_rule` - Delete a rule
### Search & Discovery
- `search` - Search across all plan items
- `advanced_search` - Advanced search with filters
### Data Management
- `backup_database` - Create a database backup
- `restore_database` - Restore from backup
- `sync_filesystem` - Sync database to filesystem
## MCP Resources
- `plan://index` - Project plan overview (Markdown)
- `plan://tasks` - All tasks (JSON)
- `plan://features` - All features (JSON)
- `plan://bugs` - All bugs (JSON)
- `plan://rules` - All rules (JSON)
- `plan://stats` - Project statistics (JSON)
## Configuration
### Claude Desktop
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"follow-plan": {
"command": "node",
"args": [
"/path/to/follow-plan-mcp/dist/index.js",
"/path/to/your/project"
],
"env": {}
}
}
}
```
### Environment Variables
- `LOG_LEVEL` - Set logging level (debug, info, warn, error)
- `PLAN_AUTO_SYNC` - Enable/disable auto-sync (default: true)
- `PLAN_BACKUP_INTERVAL` - Backup interval in seconds (default: 1800)
## Development
### Build
```bash
npm run build
```
### Test
```bash
npm test
npm run test:coverage
```
### Lint
```bash
npm run lint
npm run lint:fix
```
### Format
```bash
npm run format
```
## Database Schema
The server uses SQLite with FTS5 full-text search. Key tables:
- `tasks` - Project tasks
- `features` - Feature specifications
- `bugs` - Bug reports
- `rules` - Project rules
- `messages` - Communication logs
- `prompts` - AI prompt templates
- `cascades` - Automation workflows
- `fts_search` - Full-text search index
## Architecture
```
src/
├── index.ts # Main MCP server
├── types/ # TypeScript type definitions
├── services/ # Business logic services
│ ├── database-service.ts
│ ├── task-service.ts
│ ├── feature-service.ts
│ ├── bug-service.ts
│ ├── rule-service.ts
│ ├── search-service.ts
│ └── persistence-service.ts
├── handlers/ # MCP request handlers
│ ├── tools.ts
│ ├── resources.ts
│ ├── validation.ts
│ └── search-handlers.ts
├── utils/ # Utility functions
└── constants/ # Application constants
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request
## License
MIT License - see LICENSE file for details
## Support
For issues and questions:
- GitHub Issues: [Report a bug or request a feature]
- Documentation: See the `/docs` directory
- Examples: See the `/examples` directory
---
**Follow Plan MCP** - Intelligent project planning for the AI age 🚀
