aifastdb-devplan

AI-Powered Development Plan Management — MCP Server

Let AI assistants (Cursor / Claude Desktop) manage your development plans, task tracking, and project documentation.
Built on the aifastdb high-performance storage engine, seamlessly integrated with AI via the MCP protocol.

让 AI 助手（Cursor / Claude Desktop）直接管理你的开发计划、任务追踪和项目文档。
基于 aifastdb 高性能存储引擎，通过 MCP 协议 与 AI 无缝集成。

English | 中文

English

Why aifastdb-devplan?

In the age of AI-assisted programming, developers collaborate with AI assistants more closely than ever. However, AI assistants lack persistent project memory — each conversation starts from scratch, with no knowledge of the overall project plan, current progress, or historical decisions.

aifastdb-devplan solves this problem by providing AI assistants with a set of structured development plan management tools, enabling AI to:

• 📋 Understand the big picture — Read project overviews, technical designs, API specifications, and more
• 🎯 Track task progress — Manage two-level task hierarchies (MainTask → SubTask) with real-time progress updates
• 🔗 Anchor to Git history — Automatically record Git commit hashes when completing tasks, with rollback detection
• 📦 Modular management — Organize tasks and docs by feature modules for a clear project architecture view
• 📄 Export documentation — Generate complete Markdown-formatted development plan documents in one click

Key Features

Quick Start

Installation

npm install -g aifastdb-devplan

Option A: As an MCP Server (Recommended)

Configure in Cursor IDE (.cursor/mcp.json):

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "npx",
      "args": ["aifastdb-devplan"]
    }
  }
}

Or in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "npx",
      "args": ["aifastdb-devplan"]
    }
  }
}

Once configured, your AI assistant can use 20 devplan_* tools to manage your development plans.

Option B: As an npm Package (Programmatic)

import { DevPlanStore, createDevPlan } from 'aifastdb-devplan';

const plan = createDevPlan('my-project');

// Create a main task
plan.createMainTask({
  projectName: 'my-project',
  taskId: 'phase-1',
  title: 'Phase 1: Foundation Setup',
  priority: 'P0',
});

// Add a subtask
plan.addSubTask({
  projectName: 'my-project',
  taskId: 'T1.1',
  parentTaskId: 'phase-1',
  title: 'Initialize project structure',
});

// Complete task (auto-updates progress + Git commit anchoring)
plan.completeSubTask('T1.1');

// Check progress
const progress = plan.getProgress();
console.log(progress);

MCP Tools (20 total)

📋 Document Management

🎯 Task Management

📦 Module Management

🔧 Utilities

Dual Storage Engine

Each project can independently choose its storage engine:

Engine selection priority:

1. Explicit engine parameter in createDevPlan()
2. .devplan/{project}/engine.json configuration
3. Auto-detect existing JSONL files → document
4. New projects → graph

Graph Visualization

Visualize your development plan as an interactive graph:

npm run visualize -- --project my-project --base-path /path/to/.devplan
# or
aifastdb-devplan-visual --project my-project --port 3210

The built-in HTTP server serves a self-contained HTML page with vis-network, featuring:

• 5 node types: project (star), module (diamond), main-task (circle), sub-task (dot), document (box)
• Status-based coloring: completed (green), in-progress (blue), pending (gray)
• Interactive features: click for details panel, filter by type, stats bar with progress
• Dark theme: consistent with modern development tools

Enable DevPlan in Other Projects (Step-by-Step Guide)

Here's a complete guide to enable devplan in any project (e.g., my-app).

Method 1: npm Published Version (Recommended)

Step 1: Install globally

npm install -g aifastdb-devplan

Step 2: Configure MCP Server in your project

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "npx",
      "args": ["aifastdb-devplan"]
    }
  }
}

Step 3: Start using with AI assistant

Open Cursor in your project directory and tell the AI:

Initialize a development plan for my-app project

The AI will call devplan_init and data will be stored in .devplan/my-app/ under your project root (auto-detected via .git or package.json).

Method 2: Local Development Version

If you're working with a local clone of aifastdb-devplan (not yet published or testing changes):

Step 1: Build locally

cd /path/to/aifastdb-devplan
npm install
npm run build

Step 2: Configure MCP Server with local path

Create .cursor/mcp.json in your target project:

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "node",
      "args": ["/path/to/aifastdb-devplan/dist/mcp-server/index.js"]
    }
  }
}

Windows example:

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "node",
      "args": ["D:/Project/git/aifastdb-devplan/dist/mcp-server/index.js"]
    }
  }
}

Controlling Data Storage Location

By default, devplan auto-detects your project root and stores data in .devplan/. You can override this:

Option A: Environment variable (global override)

# All devplan data will be stored under this path
export AIFASTDB_DEVPLAN_PATH=/path/to/shared/devplans

Option B: --base-path for visualization server

# View another project's devplan graph
aifastdb-devplan-visual --project my-app --base-path /path/to/my-app/.devplan --port 3210

--base-path Parameter Details

Data directory structure under --base-path:

<base-path>/
└── <project-name>/
    ├── engine.json        # Engine config
    ├── graph-data/        # Graph engine data (WAL shards)
    ├── documents.jsonl    # Document engine data
    ├── tasks.jsonl
    └── modules.jsonl

Complete Example: Managing "my-app" from Scratch

# 1. Install devplan globally
npm install -g aifastdb-devplan

# 2. Go to your project
cd /path/to/my-app

# 3. Create MCP config
mkdir -p .cursor
echo '{"mcpServers":{"aifastdb-devplan":{"command":"npx","args":["aifastdb-devplan"]}}}' > .cursor/mcp.json

# 4. Open in Cursor and tell AI:
#    "Initialize devplan for my-app, create Phase 1 with 3 subtasks"

# 5. Visualize the plan graph
npx aifastdb-devplan-visual --project my-app --base-path .devplan --port 3210

Data Storage

Data is stored locally — no external database required:

.devplan/{projectName}/
├── engine.json        # Engine configuration (graph or document)
├── documents.jsonl    # Document sections (document engine)
├── tasks.jsonl        # Main tasks + subtasks (document engine)
├── modules.jsonl      # Feature modules (document engine)
└── graph-data/        # WAL-based graph storage (graph engine)
    └── wal/           # Write-ahead log shards

Storage path resolution priority:

Platform Support

aifastdb-devplan is a pure TypeScript/JavaScript project, supporting all platforms with Node.js ≥ 18:

Note: The underlying storage engine aifastdb includes Rust native bindings with prebuilt binaries for all listed platforms.

中文

为什么需要 aifastdb-devplan？

在 AI 辅助编程时代，开发者与 AI 助手的协作越来越密切。但 AI 助手缺乏持久化的项目记忆——每次对话都从零开始，无法了解项目的整体规划、当前进度和历史决策。

aifastdb-devplan 解决了这个问题：它为 AI 助手提供了一套结构化的开发计划管理工具，让 AI 能够：

• 📋 了解项目全貌 — 读取项目概述、技术方案、API 设计等文档片段
• 🎯 追踪任务进度 — 管理两级任务层级（主任务 → 子任务），实时更新进度
• 🔗 锚定 Git 历史 — 完成任务时自动记录 Git commit hash，支持回滚检测
• 📦 模块化管理 — 按功能模块组织任务和文档，清晰展示项目架构
• 📄 导出文档 — 一键生成完整的 Markdown 格式开发计划文档

核心特性

快速开始

安装

npm install -g aifastdb-devplan

方式 A：作为 MCP Server 使用（推荐）

在 Cursor IDE 中配置 .cursor/mcp.json：

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "npx",
      "args": ["aifastdb-devplan"]
    }
  }
}

或在 Claude Desktop 中配置 claude_desktop_config.json：

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "npx",
      "args": ["aifastdb-devplan"]
    }
  }
}

配置完成后，AI 助手即可使用 20 个 devplan_* 工具来管理你的开发计划。

方式 B：作为 npm 包编程使用

import { DevPlanStore, createDevPlan } from 'aifastdb-devplan';

const plan = createDevPlan('my-project');

// 创建主任务
plan.createMainTask({
  projectName: 'my-project',
  taskId: 'phase-1',
  title: '阶段一：基础搭建',
  priority: 'P0',
});

// 添加子任务
plan.addSubTask({
  projectName: 'my-project',
  taskId: 'T1.1',
  parentTaskId: 'phase-1',
  title: '初始化项目结构',
});

// 完成任务（自动更新主任务进度 + Git commit 锚定）
plan.completeSubTask('T1.1');

// 查看进度
const progress = plan.getProgress();
console.log(progress);

MCP 工具一览（20 个）

📋 文档管理

🎯 任务管理

📦 模块管理

🔧 工具

双存储引擎

每个项目可独立选择存储引擎：

引擎选择优先级：

1. createDevPlan() 显式传入 engine 参数
2. .devplan/{project}/engine.json 配置文件
3. 已有 JSONL 数据文件 → 自动识别为 document
4. 新项目 → 默认使用 graph

图谱可视化

将开发计划以交互式图谱形式展示：

npm run visualize -- --project my-project --base-path /path/to/.devplan
# 或
aifastdb-devplan-visual --project my-project --port 3210

内置 HTTP 服务器提供自包含 HTML 页面，使用 vis-network 渲染：

• 5 种节点类型：项目（星形）、模块（菱形）、主任务（圆形）、子任务（小圆点）、文档（方形）
• 状态着色：已完成（绿色）、进行中（蓝色）、待开始（灰色）
• 交互功能：点击查看详情面板、按类型过滤、顶部统计栏 + 进度条
• 暗色主题：与现代开发工具风格一致

在其它项目中启用 DevPlan（实战指南）

以下是在任意项目（例如 my-app）中启用 devplan 的完整步骤。

方式一：使用 npm 发布版本（推荐）

第 1 步：全局安装

npm install -g aifastdb-devplan

第 2 步：在目标项目中配置 MCP Server

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "npx",
      "args": ["aifastdb-devplan"]
    }
  }
}

第 3 步：通过 AI 助手开始使用

在 Cursor 中打开你的项目目录，对 AI 说：

为 my-app 项目初始化开发计划

AI 会调用 devplan_init，数据自动存储在项目根目录下的 .devplan/my-app/ 中（通过 .git 或 package.json 自动检测项目根目录）。

方式二：使用本地开发版本

如果你在使用本地克隆的 aifastdb-devplan（未发布到 npm 或正在测试修改）：

第 1 步：本地构建

cd /path/to/aifastdb-devplan
npm install
npm run build

第 2 步：使用本地路径配置 MCP Server

在目标项目中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "node",
      "args": ["/path/to/aifastdb-devplan/dist/mcp-server/index.js"]
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "aifastdb-devplan": {
      "command": "node",
      "args": ["D:/Project/git/aifastdb-devplan/dist/mcp-server/index.js"]
    }
  }
}

控制数据存储位置

默认情况下，devplan 会自动检测项目根目录并将数据存储在 .devplan/ 下。你可以通过以下方式覆盖：

方案 A：环境变量（全局覆盖）

# 所有 devplan 数据将存储在此路径下
export AIFASTDB_DEVPLAN_PATH=/path/to/shared/devplans

Windows PowerShell：

$env:AIFASTDB_DEVPLAN_PATH = "D:\shared\devplans"

方案 B：可视化服务器使用 --base-path

# 查看另一个项目的 devplan 图谱
aifastdb-devplan-visual --project my-app --base-path /path/to/my-app/.devplan --port 3210

--base-path 参数详解

--base-path 下的数据目录结构：

<base-path>/
└── <project-name>/
    ├── engine.json        # 引擎配置
    ├── graph-data/        # Graph 引擎数据（WAL 分片）
    ├── documents.jsonl    # Document 引擎数据
    ├── tasks.jsonl
    └── modules.jsonl

完整示例：从零管理 "my-app" 项目

# 1. 全局安装 devplan
npm install -g aifastdb-devplan

# 2. 进入你的项目目录
cd /path/to/my-app

# 3. 创建 MCP 配置
mkdir -p .cursor
echo '{"mcpServers":{"aifastdb-devplan":{"command":"npx","args":["aifastdb-devplan"]}}}' > .cursor/mcp.json

# 4. 在 Cursor 中打开项目，对 AI 说：
#    "为 my-app 初始化开发计划，创建阶段一并添加 3 个子任务"

# 5. 可视化查看计划图谱
npx aifastdb-devplan-visual --project my-app --base-path .devplan --port 3210

数据存储

数据存储在本地，无需外部数据库：

.devplan/{projectName}/
├── engine.json        # 引擎配置（graph 或 document）
├── documents.jsonl    # 文档片段（document 引擎）
├── tasks.jsonl        # 主任务 + 子任务（document 引擎）
├── modules.jsonl      # 功能模块（document 引擎）
└── graph-data/        # WAL 图存储（graph 引擎）
    └── wal/           # 预写日志分片

存储路径解析优先级：

平台支持

aifastdb-devplan 是纯 TypeScript/JavaScript 项目，支持所有 Node.js ≥ 18 的平台：

注：底层存储引擎 aifastdb 包含 Rust 原生绑定，已为上述平台提供预编译二进制文件。

Tech Stack / 技术栈

• Storage Engine / 存储引擎: aifastdb — Dual engine: SocialGraphV2 (graph) + EnhancedDocumentStore (JSONL), built with Rust + N-API
• Protocol / 通信协议: MCP (Model Context Protocol) — Standard protocol for AI assistant tool invocation
• Visualization / 可视化: vis-network — Interactive graph visualization (CDN, zero dependencies)
• Runtime / 运行时: Node.js ≥ 18
• Language / 语言: TypeScript (strict mode)

Related Projects / 相关项目

• aifastdb — AI-friendly high-performance database engine (vector search + semantic indexing + agent memory)
• MCP Protocol — Model Context Protocol official documentation

License

MIT