### Initialize and Start MCP Service in TypeScript

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

This TypeScript code demonstrates how to import, initialize, and start the McpService using the provided SDK. It includes configuration parsing, logger setup, and graceful shutdown handling.

```typescript
import { McpService } from 'feishu-project-mcp/core/server';
import { Logger } from 'feishu-project-mcp/utils/logger';
import { parseConfig } from 'feishu-project-mcp/utils/config';
import { TaskManager } from 'feishu-project-mcp/managers/task';
import { FeishuIntegrator } from 'feishu-project-mcp/integrators/feishu';
import { TaskStatus, TaskType } from 'feishu-project-mcp/types/task';

// 初始化配置
const config = parseConfig([
  '--port', '3000',
  '--host', 'localhost',
  '--feishu-app-id', 'your_app_id',
  '--feishu-app-secret', 'your_app_secret'
]);

// 初始化日志记录器
const logger = new Logger({
  level: 'info',
  logDir: './logs',
  serviceName: 'my-mcp-client'
});

// 初始化并启动服务
const service = new McpService(config, logger);

async function main() {
  try {
    await service.initialize();
    await service.start();

    console.log(`服务运行在 ${config.host}:${config.port}`);

    // 优雅关闭处理
    process.on('SIGINT', async () => {
      if (service.isRunning()) {
        await service.stop();
      }
      process.exit(0);
    });
  } catch (error) {
    console.error('启动失败:', error);
    process.exit(1);
  }
}

main();
```

--------------------------------

### Install and Run Feishu Project MCP

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Install dependencies, configure environment variables via a .env file, and run the service in development or production mode. Alternatively, use npx for direct execution.

```bash
npm install
```

```bash
cat > .env << 'EOF'\n# Feishu API Configuration\nFEISHU_APP_ID=your_app_id\nFEISHU_APP_SECRET=your_app_secret\nFEISHU_API_URL=https://project.feishu.cn/open_api\n\n# Service Configuration\nCHECK_INTERVAL=5000\nSTORAGE_DIR=./storage\nLOG_DIR=./logs\nLOG_LEVEL=info\nMAX_CONCURRENT_TASKS=5\n\n# Server Configuration\nPORT=3000\nHOST=localhost\nEOF
```

```bash
npm run dev
```

```bash
npm run build && npm start
```

```bash
npx feishu-project-mcp start --port 3000 --host localhost
```

--------------------------------

### Install Semantic Release

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Install semantic-release and its required plugins as development dependencies.

```bash
npm install --save-dev semantic-release @semantic-release/git @semantic-release/github @semantic-release/npm @semantic-release/changelog @semantic-release/commit-analyzer @semantic-release/release-notes-generator
```

--------------------------------

### Verify Published Package

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Test the published package by installing it via npx.

```bash
npx feishu-project-mcp
```

--------------------------------

### Get Feishu Project List

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Use this command to fetch a list of projects from Feishu. This is the first step in analyzing Feishu-related data.

```bash
curl -X POST -H "Content-Type: application/json" -d '{"tool":"feishu.projects"}' http://localhost:3000/mcp
```

--------------------------------

### Feishu Project MCP CLI Commands

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Utilize the command-line interface to start the MCP service with various configuration options, check service health, or view version information.

```bash
feishu-project-mcp start \
  --port 3000 \
  --host localhost \
  --feishu-app-id cli_xxxx \
  --feishu-app-secret secret_xxxx \
  --feishu-api-url https://project.feishu.cn/open_api \
  --storage-dir ./storage \
  --log-dir ./logs \
  --log-level info \
  --max-concurrent-tasks 5
```

```bash
feishu-project-mcp health --port 3000 --host localhost
```

```bash
feishu-project-mcp version
```

--------------------------------

### MCP Tools Reference

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/docs/design.md

A reference guide to the available MCP tools and their functionalities.

```APIDOC
## MCP Tools

### Health Check Tools
- **health**: Get the complete health status of the system.
- **health.components**: Get the health status of individual system components.
- **health.integrations**: Get the health status of external integrations.
- **health.tasks**: Get the health status of the task manager.
- **health.memory**: Get memory usage statistics.

### Feishu Integration Tools
- **feishu.projects**: Retrieve a list of Feishu projects.
- **feishu.requirements**: Retrieve a list of requirements for a given project.
- **feishu.bugs**: Retrieve a list of bugs for a given project.

### Task Management Tools
- **task.create**: Create a new task.
- **task.get**: Retrieve details of a specific task.

### Mode Tools
- **mode.analyze**: Analyze a requirement or bug.
- **mode.implement**: Implement a requirement or fix a bug.
```

--------------------------------

### MCP Tool - Get Feishu Projects

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Fetch a list of all accessible Feishu projects by sending a POST request to the /mcp endpoint with the 'feishu.projects' tool specified.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "feishu.projects"}'
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

An example of a commit message following the Conventional Commits specification, including type, scope, subject, body, and footer.

```git
feat(server): add health check endpoint

Add a new endpoint to check the health of the server and its components.

Closes #123
```

--------------------------------

### Get Feishu Requirement List

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Use this command to retrieve a list of requirements for a specific project from Feishu. Requires a projectId.

```bash
curl -X POST -H "Content-Type: application/json" -d '{"tool":"feishu.requirements","params":{"projectId":"project1"}}' http://localhost:3000/mcp
```

--------------------------------

### GET /health

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Retrieves the system health status, including components, integrations, tasks, and memory usage.

```APIDOC
## GET /health

### Description
Returns the system health status, including component status, integration status, task status, and memory usage.

### Method
GET

### Endpoint
/health
```

--------------------------------

### MCP Tool - Get Feishu Requirements

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Retrieve all requirements for a specific project by sending a POST request to the /mcp endpoint with 'feishu.requirements' as the tool and providing the projectId in the params.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "feishu.requirements",
    "params": {
      "projectId": "project_001"
    }
  }'
```

--------------------------------

### MCP Tool - Get Feishu Bugs

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Fetch all bugs for a specific project by sending a POST request to the /mcp endpoint with 'feishu.bugs' as the tool and providing the projectId in the params.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "feishu.bugs",
    "params": {
      "projectId": "project_001"
    }
  }'
```

--------------------------------

### Get Task Status

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Use this command to retrieve the details of a specific task. Requires a taskId.

```bash
curl -X POST -H "Content-Type: application/json" -d '{"tool":"task.get","params":{"taskId":"task1"}}' http://localhost:3000/mcp
```

--------------------------------

### HTTP API - Health Check

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Retrieve comprehensive system health status, including component, integration, task, and memory utilization details, by sending a GET request to the /health endpoint.

```bash
curl -X GET http://localhost:3000/health
```

--------------------------------

### Build and Publish Manually

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Commands for building, testing locally, and publishing the package to the npm registry.

```bash
npm run build
```

```bash
npm pack
```

```bash
npm install /path/to/feishu-project-mcp-1.0.0.tgz
```

```bash
npm publish
```

```bash
npm publish --access=public
```

--------------------------------

### Implement Task using MCP Tool Protocol

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Initiates an implementation task by sending a POST request to the MCP service. Requires the BASE_URL and a REQ_ID. The output is piped to jq for pretty-printing.

```bash
IMPL_TASK=$(curl -s -X POST $BASE_URL \
  -H "Content-Type: application/json" \
  -d "{\"tool\": \"mode.implement\", \"params\": {\"itemId\": \"$REQ_ID\", \"itemType\": \"requirement\"}}")
echo $IMPL_TASK | jq
```

--------------------------------

### 使用Docker部署

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

构建镜像并运行容器。

```bash
# 构建镜像
docker build -t feishu-project-mcp .

# 运行容器
docker run -p 3000:3000 --env-file .env feishu-project-mcp
```

--------------------------------

### Create System Tasks

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Create new tasks for requirement analysis or code implementation using the task.create tool.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "task.create",
    "params": {
      "type": "requirement_analysis",
      "itemId": "req_001",
      "itemType": "requirement"
    }
  }'
```

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "task.create",
    "params": {
      "type": "code_implementation",
      "itemId": "req_001",
      "itemType": "requirement"
    }
  }'
```

--------------------------------

### 运行项目

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

启动开发模式或构建并运行生产环境。

```bash
# 开发模式
npm run dev

# 生产模式
npm run build
npm start
```

--------------------------------

### Get Memory Usage Status

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

This cURL command retrieves the memory usage statistics of the MCP service. It's useful for monitoring resource consumption.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "health.memory"}'
```

```json
{"success": true, "data": {"heapUsed": 45, "heapTotal": 65, "external": 2, "systemTotal": 16384, "systemFree": 8192, "systemUsagePercent": 50}}
```

--------------------------------

### Define package.json

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Configuration file specifying project metadata, entry points, and dependencies.

```json
{
  "name": "feishu-project-mcp",
  "version": "1.0.0",
  "description": "Feishu Project MCP Service for end-to-end requirement management and development automation",
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "feishu-project-mcp": "dist/cli.js"
  },
  "files": ["dist", "LICENSE", "README.md"],
  "keywords": [
    "feishu",
    "mcp",
    "project-management",
    "automation",
    "requirements",
    "development"
  ],
  "author": "Your Name <your.email@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/yourusername/feishu-project-mcp.git"
  },
  "bugs": {
    "url": "https://github.com/yourusername/feishu-project-mcp/issues"
  },
  "homepage": "https://github.com/yourusername/feishu-project-mcp#readme"
}
```

--------------------------------

### 配置环境变量

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

在项目根目录创建.env文件以配置飞书API凭证及服务参数。

```text
# Feishu API Configuration
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
FEISHU_API_URL=https://project.feishu.cn/open_api

# Service Configuration
CHECK_INTERVAL=5000
STORAGE_DIR=./storage
LOG_DIR=./logs
LOG_LEVEL=info
MAX_CONCURRENT_TASKS=5

# Server Configuration
PORT=3000
HOST=localhost
```

--------------------------------

### Health Check API Endpoint

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Use this GET endpoint to retrieve the system's overall health status, including component, integration, task, and memory usage.

```http
GET /health
```

--------------------------------

### Build and Run MCP Docker Image

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Commands for building a Docker image for feishu-project-mcp and running it as a container. It supports using environment files for configuration.

```bash
# 构建Docker镜像
docker build -t feishu-project-mcp .

# 运行容器（使用环境变量文件）
docker run -d \
  --name feishu-mcp \
  -p 3000:3000 \
  --env-file .env \
  feishu-project-mcp
```

```bash
docker-compose up -d
```

```yaml
# docker-compose.yml 示例配置
# version: '3.8'
# services:
#   feishu-mcp:
#     build: .
#     ports:
#       - "3000:3000"
#     environment:
#       - FEISHU_APP_ID=${FEISHU_APP_ID}
#       - FEISHU_APP_SECRET=${FEISHU_APP_SECRET}
#       - FEISHU_API_URL=https://project.feishu.cn/open_api
#       - PORT=3000
#       - HOST=0.0.0.0
#       - LOG_LEVEL=info
#     volumes:
#       - ./storage:/app/storage
#       - ./logs:/app/logs
```

```bash
# 检查容器健康状态
docker exec feishu-mcp curl -s http://localhost:3000/health | jq
```

--------------------------------

### 安装项目依赖

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

克隆仓库并安装必要的Node.js依赖。

```bash
# 克隆仓库
git clone https://github.com/yourusername/feishu-project-mcp.git
cd feishu-project-mcp

# 安装依赖
npm install
```

--------------------------------

### Get Task Health Status

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Use this cURL command to query the health status of tasks within the MCP service. Ensure the service is running on http://localhost:3000.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "health.tasks"}'
```

```json
{"success": true, "data": {"total": 10, "pending": 2, "inProgress": 3, "completed": 4, "failed": 1}}
```

--------------------------------

### 发布后使用npx

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

项目发布到npm注册表后的调用方式。

```bash
npx feishu-project-mcp [参数]
```

```bash
npx feishu-project-mcp@1.0.0 [参数]
```

--------------------------------

### Configure Semantic Release

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Configuration file for semantic-release plugins.

```json
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    "@semantic-release/git"
  ]
}
```

--------------------------------

### 使用npx调用本地项目

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

在发布前通过npx调用本地构建的项目。

```bash
# 先构建项目
npm run build

# 使用npx调用本地包
npx . [参数]
```

```bash
npx /path/to/feishu-project-mcp [参数]
```

--------------------------------

### GitHub Actions Workflow for Semantic Release

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Automates versioning and publishing based on commit messages.

```yaml
name: Semantic Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: '18.x'
          registry-url: 'https://registry.npmjs.org/'
      - run: npm ci
      - run: npm run build
      - run: npm test
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
```

--------------------------------

### 传递npx参数

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

向npx命令传递运行时参数。

```bash
npx . --port 3001 --host 0.0.0.0
```

--------------------------------

### Login to npm

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Authenticate the local terminal with your npm account.

```bash
npm login
```

--------------------------------

### GitHub Actions Workflow for npm Publishing

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Automates the build and publish process upon creating a GitHub release.

```yaml
name: Publish to npm

on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18.x'
          registry-url: 'https://registry.npmjs.org/'
      - run: npm ci
      - run: npm run build
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
```

--------------------------------

### 在Cline中配置MCP服务

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

在cline_mcp_settings.json中添加服务配置。

```json
"feishu-project-mcp": {
  "command": "node",
  "args": [
    "/path/to/feishu-project-mcp/dist/index.js"
  ],
  "env": {
    "FEISHU_APP_ID": "your_app_id",
    "FEISHU_APP_SECRET": "your_app_secret",
    "FEISHU_API_URL": "https://project.feishu.cn/open_api"
  },
  "disabled": false,
  "alwaysAllow": [
    "health",
    "health.components",
    "health.integrations",
    "health.tasks",
    "health.memory",
    "feishu.projects",
    "feishu.requirements",
    "feishu.bugs",
    "task.create",
    "task.get",
    "mode.analyze",
    "mode.implement"
  ]
}
```

```json
"feishu-project-mcp": {
  "command": "npx",
  "args": [
    "feishu-project-mcp"
  ],
  "env": {
    "FEISHU_APP_ID": "your_app_id",
    "FEISHU_APP_SECRET": "your_app_secret",
    "FEISHU_API_URL": "https://project.feishu.cn/open_api"
  },
  "disabled": false,
  "alwaysAllow": [
    "health",
    "health.components",
    "health.integrations",
    "health.tasks",
    "health.memory",
    "feishu.projects",
    "feishu.requirements",
    "feishu.bugs",
    "task.create",
    "task.get",
    "mode.analyze",
    "mode.implement"
  ]
}
```

```json
"feishu-project-mcp": {
  "command": "npx",
  "args": [
    "/absolute/path/to/feishu-project-mcp"
  ],
  "env": {
    "FEISHU_APP_ID": "your_app_id",
    "FEISHU_APP_SECRET": "your_app_secret",
    "FEISHU_API_URL": "https://project.feishu.cn/open_api"
  },
  "disabled": false,
  "alwaysAllow": [
    "health",
    "health.components",
    "health.integrations",
    "health.tasks",
    "health.memory",
    "feishu.projects",
    "feishu.requirements",
    "feishu.bugs",
    "task.create",
    "task.get",
    "mode.analyze",
    "mode.implement"
  ]
}
```

--------------------------------

### 飞书项目数据模型定义

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/docs/design.md

定义了飞书项目、需求和缺陷的数据结构接口。

```typescript
interface FeishuProject {
  id: string;
  name: string;
  description?: string;
  created_at: string;
  updated_at: string;
  owner: FeishuUser;
  status: string;
}

interface FeishuRequirement {
  id: string;
  title: string;
  description: string;
  priority: string;
  status: string;
  created_at: string;
  updated_at: string;
  creator: FeishuUser;
  assignee?: FeishuUser;
  project_id: string;
  attachments?: FeishuAttachment[];
  comments?: FeishuComment[];
  custom_fields?: Record<string, any>;
}

interface FeishuBug {
  id: string;
  title: string;
  description: string;
  priority: string;
  severity: string;
  status: string;
  created_at: string;
  updated_at: string;
  creator: FeishuUser;
  assignee?: FeishuUser;
  project_id: string;
  attachments?: FeishuAttachment[];
  comments?: FeishuComment[];
  custom_fields?: Record<string, any>;
}
```

--------------------------------

### Implement Requirements or Fix Bugs

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Initiate the development process for a requirement or bug fix using the mode.implement tool.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "mode.implement",
    "params": {
      "itemId": "req_001",
      "itemType": "requirement"
    }
  }'
```

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "mode.implement",
    "params": {
      "itemId": "bug_001",
      "itemType": "bug"
    }
  }'
```

--------------------------------

### POST /mcp

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Executes a specific MCP tool with provided parameters.

```APIDOC
## POST /mcp

### Description
Executes an MCP tool based on the provided tool name and parameters.

### Method
POST

### Endpoint
/mcp

### Request Body
- **tool** (string) - Required - The name of the tool to execute (e.g., 'health', 'feishu.projects', 'task.create', 'mode.analyze')
- **params** (object) - Optional - Parameters required by the specific tool

### Request Example
{
  "tool": "feishu.requirements",
  "params": {
    "projectId": "project1"
  }
}
```

--------------------------------

### Analyze Requirement

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Use this command to analyze a specific requirement. Requires an itemId and itemType.

```bash
curl -X POST -H "Content-Type: application/json" -d '{"tool":"mode.analyze","params":{"itemId":"requirement1","itemType":"requirement"}}' http://localhost:3000/mcp
```

--------------------------------

### Configure MCP Server in Cline IDE

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

This JSON configuration is used within Cline IDE to set up the feishu-project-mcp service. It includes command execution details, environment variables, and allowed tools.

```json
{
  "mcpServers": {
    "feishu-project-mcp": {
      "command": "npx",
      "args": ["feishu-project-mcp"],
      "env": {
        "FEISHU_APP_ID": "your_app_id",
        "FEISHU_APP_SECRET": "your_app_secret",
        "FEISHU_API_URL": "https://project.feishu.cn/open_api"
      },
      "disabled": false,
      "alwaysAllow": [
        "health",
        "health.components",
        "health.integrations",
        "health.tasks",
        "health.memory",
        "feishu.projects",
        "feishu.requirements",
        "feishu.bugs",
        "task.create",
        "task.get",
        "mode.analyze",
        "mode.implement"
      ]
    }
  }
}
```

--------------------------------

### POST /mcp

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Unified endpoint for executing MCP tools including project listing, requirement retrieval, and bug tracking.

```APIDOC
## POST /mcp

### Description
Executes specific MCP tools to interact with Feishu project data.

### Method
POST

### Endpoint
/mcp

### Request Body
- **tool** (string) - Required - The name of the tool to execute (e.g., "feishu.projects", "feishu.requirements", "feishu.bugs")
- **params** (object) - Optional - Parameters required by the specific tool

### Request Example
{
  "tool": "feishu.requirements",
  "params": {
    "projectId": "project_001"
  }
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful
- **data** (array/object) - The requested data payload

#### Response Example
{
  "success": true,
  "data": []
}
```

--------------------------------

### Retrieve Task Details

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Fetch status, progress, and results for a specific task using its ID.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "task.get",
    "params": {
      "taskId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'
```

--------------------------------

### 任务数据模型定义

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/docs/design.md

定义了任务类型、状态枚举以及任务对象的接口结构。

```typescript
enum TaskType {
  REQUIREMENT_ANALYSIS = 'requirement_analysis',
  BUG_ANALYSIS = 'bug_analysis',
  CODE_IMPLEMENTATION = 'code_implementation',
  CODE_REVIEW = 'code_review',
  DOCUMENTATION = 'documentation',
}

enum TaskStatus {
  PENDING = 'pending',
  IN_PROGRESS = 'in_progress',
  COMPLETED = 'completed',
  FAILED = 'failed',
  CANCELLED = 'cancelled',
}

interface Task {
  id: string;
  type: TaskType;
  status: TaskStatus;
  itemId: string;
  itemType: string;
  created_at: string;
  updated_at: string;
  completed_at?: string;
  failed_at?: string;
  cancelled_at?: string;
  result?: any;
  error?: string;
}
```

--------------------------------

### Configure .npmignore

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Specify files and directories to exclude from the published npm package.

```text
.git
.github
.husky
.vscode
node_modules
src
tests
.editorconfig
.env*
.eslintrc*
.gitignore
.lintstagedrc*
.prettierrc
commitlint.config.cjs
docker-compose*
Dockerfile*
jest.config.cjs
nodemon.json
tsconfig.json
```

--------------------------------

### Implementation Mode API

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Implement requirements or fix defects by creating code implementation tasks and initiating the development process based on analysis results.

```APIDOC
## POST /mcp (mode.implement)

### Description
Implements a requirement or fixes a defect by creating a code implementation task and initiating the development process based on analysis results.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **tool** (string) - Required - Specifies the tool to use, which is 'mode.implement' for this operation.
- **params** (object) - Required - Contains parameters for the implementation.
  - **itemId** (string) - Required - The ID of the item to implement or fix (e.g., requirement ID, bug ID).
  - **itemType** (string) - Required - The type of the item. Accepted values are: 'requirement', 'bug'.

### Request Example (Implement Requirement)
```json
{
  "tool": "mode.implement",
  "params": {
    "itemId": "req_001",
    "itemType": "requirement"
  }
}
```

### Request Example (Fix Defect)
```json
{
  "tool": "mode.implement",
  "params": {
    "itemId": "bug_001",
    "itemType": "bug"
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the details of the implementation task.
  - **id** (string) - The unique identifier for the implementation task.
  - **type** (string) - The type of the task, typically 'code_implementation'.
  - **status** (string) - The current status of the implementation task (e.g., 'pending').
  - **itemId** (string) - The ID of the implemented item.
  - **itemType** (string) - The type of the implemented item.
  - **created_at** (string) - Timestamp when the implementation task was created.
  - **updated_at** (string) - Timestamp when the implementation task was last updated.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "type": "code_implementation",
    "status": "pending",
    "itemId": "req_001",
    "itemType": "requirement",
    "created_at": "2024-01-15T17:00:00.000Z",
    "updated_at": "2024-01-15T17:00:00.000Z"
  }
}
```
```

--------------------------------

### 任务类型和状态枚举

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/docs/specifications/workflow-management.md

定义了系统中支持的任务类型和任务状态，用于任务管理。

```typescript
enum TaskType {
  REQUIREMENT_ANALYSIS = 'requirement_analysis',
  ARCHITECTURE_DESIGN = 'architecture_design',
  CODE_IMPLEMENTATION = 'code_implementation',
  CODE_SUBMISSION = 'code_submission',
}

enum TaskStatus {
  PENDING = 'pending',
  IN_PROGRESS = 'in_progress',
  COMPLETED = 'completed',
  FAILED = 'failed',
  CANCELLED = 'cancelled',
}
```

--------------------------------

### Task Creation API

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Create new internal system tasks for various workflow stages like requirement analysis, architecture design, and code implementation.

```APIDOC
## POST /mcp (task.create)

### Description
Creates a new system internal task to track workflow stages such as requirement analysis, architecture design, and code implementation.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **tool** (string) - Required - Specifies the tool to use, which is 'task.create' for this operation.
- **params** (object) - Required - Contains parameters for the task creation.
  - **type** (string) - Required - The type of task to create. Accepted values are: 'requirement_analysis', 'architecture_design', 'code_implementation', 'code_submission'.
  - **itemId** (string) - Required - The ID of the item (e.g., requirement, bug) the task is associated with.
  - **itemType** (string) - Required - The type of the item. Accepted values are: 'requirement', 'bug'.

### Request Example
```json
{
  "tool": "task.create",
  "params": {
    "type": "requirement_analysis",
    "itemId": "req_001",
    "itemType": "requirement"
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the details of the created task.
  - **id** (string) - The unique identifier for the task.
  - **type** (string) - The type of the task.
  - **status** (string) - The current status of the task (e.g., 'pending').
  - **itemId** (string) - The ID of the associated item.
  - **itemType** (string) - The type of the associated item.
  - **created_at** (string) - Timestamp when the task was created.
  - **updated_at** (string) - Timestamp when the task was last updated.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "requirement_analysis",
    "status": "pending",
    "itemId": "req_001",
    "itemType": "requirement",
    "created_at": "2024-01-15T15:00:00.000Z",
    "updated_at": "2024-01-15T15:00:00.000Z"
  }
}
```
```

--------------------------------

### Check System Health

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

Query the health status of the system, components, or integrations.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "health"}'
```

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "health.components"}'
```

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "health.integrations"}'
```

--------------------------------

### End-to-End Workflow Script

Source: https://context7.com/im47cn/feishu-project-mcp/llms.txt

This bash script orchestrates a complete workflow, from fetching project lists and requirements to analyzing them and polling task status. It uses cURL to interact with the MCP API.

```bash
#!/bin/bash
# 完整的需求处理工作流程脚本

BASE_URL="http://localhost:3000/mcp"

# 步骤1: 获取项目列表
echo "=== 步骤1: 获取项目列表 ==="
PROJECTS=$(curl -s -X POST $BASE_URL \
  -H "Content-Type: application/json" \
  -d '{"tool": "feishu.projects"}')
echo $PROJECTS | jq '.data[0]'

PROJECT_ID=$(echo $PROJECTS | jq -r '.data[0].id')
echo "选择项目: $PROJECT_ID"

# 步骤2: 获取项目需求
echo "=== 步骤2: 获取项目需求 ==="
REQUIREMENTS=$(curl -s -X POST $BASE_URL \
  -H "Content-Type: application/json" \
  -d "{\"tool\": \"feishu.requirements\", \"params\": {\"projectId\": \"$PROJECT_ID\"}}")
echo $REQUIREMENTS | jq '.data[0]'

REQ_ID=$(echo $REQUIREMENTS | jq -r '.data[0].id')
echo "选择需求: $REQ_ID"

# 步骤3: 分析需求
echo "=== 步骤3: 分析需求 ==="
ANALYSIS_TASK=$(curl -s -X POST $BASE_URL \
  -H "Content-Type: application/json" \
  -d "{\"tool\": \"mode.analyze\", \"params\": {\"itemId\": \"$REQ_ID\", \"itemType\": \"requirement\"}}")
echo $ANALYSIS_TASK | jq

TASK_ID=$(echo $ANALYSIS_TASK | jq -r '.data.id')
echo "分析任务ID: $TASK_ID"

# 步骤4: 轮询任务状态
echo "=== 步骤4: 检查任务状态 ==="
while true; do
  TASK_STATUS=$(curl -s -X POST $BASE_URL \
    -H "Content-Type: application/json" \
    -d "{\"tool\": \"task.get\", \"params\": {\"taskId\": \"$TASK_ID\"}}")

  STATUS=$(echo $TASK_STATUS | jq -r '.data.status')
  echo "当前状态: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    echo $TASK_STATUS | jq '.data'
    break
  fi

  sleep 2
done

```

--------------------------------

### 任务数据模型

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/docs/specifications/workflow-management.md

定义了任务对象的数据结构，包含任务类型、状态、描述、关联项 ID 及时间戳等信息。

```typescript
interface Task {
  id: string;
  type: TaskType;
  status: TaskStatus;
  description?: string;
  itemId: string;
  itemType: string;
  workflowId?: string;
  workflowStage?: WorkflowStage;
  created_at: string;
  updated_at: string;
  started_at?: string;
  completed_at?: string;
  failed_at?: string;
  cancelled_at?: string;
  result?: any;
  error?: string;
  progress?: number;
  priority?: number;
  assignedTo?: string;
  metadata?: Record<string, any>;
}
```

--------------------------------

### 服务器配置接口

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/docs/specifications/workflow-management.md

定义了服务器配置的结构，包括端口、主机、版本、名称以及飞书和存储相关的配置。

```typescript
interface ServerConfig {
  port: number;
  host: string;
  version: string;
  name: string;
  feishu: FeishuIntegratorConfig;
  storage: {
    dir: string;
    maxConcurrentTasks: number;
  };
}
```

--------------------------------

### HTTP接口定义

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/docs/design.md

定义了健康检查和MCP工具调用的HTTP接口路径。

```text
GET /health
```

```text
POST /mcp
```

--------------------------------

### MCP Tool API

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/docs/design.md

Provides a general endpoint to interact with various MCP tools for performing specific operations within the Feishu Project MCP Service.

```APIDOC
## POST /mcp

### Description
This endpoint allows clients to invoke various MCP tools by sending a JSON payload specifying the tool name and its parameters. It supports operations like fetching data from Feishu, managing tasks, and analyzing or implementing development items.

### Method
POST

### Endpoint
/mcp

### Request Body
- **tool** (string) - Required - The name of the MCP tool to invoke (e.g., 'feishu.projects', 'task.create', 'mode.analyze').
- **params** (object) - Optional - An object containing the parameters required by the specified tool.

### Request Example
```json
{
  "tool": "feishu.requirements",
  "params": {
    "projectId": "your_project_id"
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful (true).
- **data** (object) - The data returned by the invoked tool.

#### Error Response
- **success** (boolean) - Indicates if the operation failed (false).
- **error** (string) - A message describing the error.

#### Response Example (Success)
```json
{
  "success": true,
  "data": [
    {
      "id": "req_123",
      "title": "Implement user login",
      "status": "open"
    }
  ]
}
```

#### Response Example (Error)
```json
{
  "success": false,
  "error": "Invalid project ID provided."
}
```
```

--------------------------------

### Update Package Version

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/README.md

Commands to manually increment the package version and push changes.

```bash
# 补丁版本更新 (1.0.0 -> 1.0.1)
npm version patch

# 次要版本更新 (1.0.0 -> 1.1.0)
npm version minor

# 主要版本更新 (1.0.0 -> 2.0.0)
npm version major
```

```bash
git push --follow-tags
npm publish
```

--------------------------------

### 工作流状态数据模型

Source: https://github.com/im47cn/feishu-project-mcp/blob/main/docs/specifications/workflow-management.md

定义了工作流状态对象的数据结构，包含 ID、需求 ID、当前阶段及时间戳等信息。

```typescript
interface WorkflowState {
  id: string;
  requirementId: string;
  currentStage: WorkflowStage;
  startedAt: string;
  updatedAt: string;
  completedAt?: string;
  analysisResult?: RequirementAnalysisResult;
  designResult?: ArchitectureDesignResult;
  implementationResult?: CodeImplementationResult;
  metadata?: Record<string, any>;
}
```