更愉悦的MCP服务器

Name: 更愉悦的MCP服务器
Author: Takashi-Matsumura

作者：Takashi-Matsumura5 星标更新：2025-06-24

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Pleasanter MCP 服务器

这是用于 Implem.Pleasanter 集成的 Model Context Protocol (MCP) 服务器。通过该服务器，AI 助手可以操作 Pleasanter 的项目和任务。

功能

工具

任务管理: 创建、读取、更新、删除任务
高级搜索: 在整个项目中进行复杂的过滤和搜索
分析功能: 趋势分析和项目状态概要
批量操作: 多个任务的高效批量处理

资源

站点: 访问可用的 Pleasanter 项目
用户/组/部门: 组织结构信息
动态资源: 实时的项目状态和任务数据

提示

项目状态报告: 自动生成的项目健康报告
任务分析: 趋势分析和推荐
团队生产力: 性能分析和洞察
优先任务识别: 识别紧急任务并制定行动计划
每周站立会议准备: 准备团队会议

安装

克隆或下载服务器代码
```
cd pleasanter-mcp-server
```
安装依赖项
```
npm install
```
构建服务器
```
npm run build
```

前提条件

Node.js 18.0.0 及以上版本（推荐：24.x LTS）
npm 或 yarn
对 Pleasanter 服务器的访问权限和 API 密钥

已验证环境

以下环境已完成构建和运行测试：

操作系统: Ubuntu 24.04.2 LTS (WSL2)
Node.js: v24.2.0
npm: v11.3.0
TypeScript: v5.8.3
平台: Windows 上的 WSL2

设置

创建环境文件
```
cp .env.example .env
```

编辑设置

# 必需设置
PLEASANTER_BASE_URL=http://10.255.20.80:50001  # 本地网络中的 Pleasanter 服务器
PLEASANTER_API_KEY=your-api-key-here          # Pleasanter 的 API 密钥

# 可选设置
PLEASANTER_TIMEOUT=30000
PLEASANTER_RETRIES=3
LOG_LEVEL=info

注意:

生产环境中请使用 HTTPS
请妥善管理 API 密钥，并定期轮换

获取 Pleasanter API 密钥
- 登录 Pleasanter 系统
- 移动到用户设置
- 生成或复制 API 密钥
- 确认账户已启用 API 访问

在 Claude Desktop 中使用

macOS 环境

添加到 Claude Desktop 设置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": ["/path/to/pleasanter-mcp-server/dist/index.js"],
      "env": {
        "PLEASANTER_BASE_URL": "https://your-pleasanter-server.com",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windows 环境

添加到 Claude Desktop 设置

编辑 %APPDATA%\Claude\claude_desktop_config.json:

选项1: 使用 WSL 命令（推荐）

{
  "mcpServers": {
    "pleasanter": {
      "command": "wsl",
      "args": [
        "node",
        "/home/ubuntu/github/Implem.Pleasanter/pleasanter-mcp-server/dist/index.js"
      ],
      "env": {
        "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
        "PLEASANTER_API_KEY": "your-api-key-here",
        "PLEASANTER_TIMEOUT": "30000",
        "PLEASANTER_RETRIES": "3",
        "LOG_LEVEL": "info"
      }
    }
  }
}

选项2: 直接指定 WSL2 路径

{
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": [
        "\\\\wsl.localhost\\Ubuntu\\home\\ubuntu\\github\\Implem.Pleasanter\\pleasanter-mcp-server\\dist\\index.js"
      ],
      "env": {
        "PLEASANTER_BASE_URL": "http://1.255.20.80:50001",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

选项3: 如果项目已复制到 Windows 侧

{
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": ["C:\\path\\to\\pleasanter-mcp-server\\dist\\index.js"],
      "env": {
        "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Linux 环境

添加到 Claude Desktop 设置

编辑 ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": ["/path/to/pleasanter-mcp-server/dist/index.js"],
      "env": {
        "PLEASANTER_BASE_URL": "https://your-pleasanter-server.com",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

重启 Claude Desktop
确认连接

在 Claude Desktop 中尝试以下提示以确认 MCP 服务器正常工作：

步骤1: 基本连接确认
```
可以列出可用的 Pleasanter 站点吗？
```
预期结果: 显示站点列表或适当的错误消息

步骤2: 资源确认
```
可用的 Pleasanter 资源有哪些？
```
预期结果: 显示如 pleasanter://sites、pleasanter://users 等资源列表

步骤3: 工具确认
```
请告诉我可用的 Pleasanter 工具和功能。
```
预期结果: 显示如 pleasanter_create_issue、pleasanter_get_issues 等工具列表

步骤4: 用户信息确认
```
请获取 Pleasanter 用户列表的前五条记录。
```
预期结果: 以 JSON 格式显示用户信息

如果遇到错误:
- 确认 API 密钥正确设置
- 确认 PLEASANTER_BASE_URL 正确
- 完全重启 Claude Desktop
- 查看 MCP 服务器日志（如控制台错误）

可用工具

任务管理

pleasanter_create_issue: 创建新任务
pleasanter_get_issues: 搜索和获取任务
pleasanter_update_issue: 更新现有任务
pleasanter_delete_issue: 删除任务
pleasanter_bulk_create_issues: 批量创建多个任务

高级搜索与分析

pleasanter_advanced_search: 使用过滤器进行复杂搜索
pleasanter_multi_site_search: 跨多个项目的搜索
pleasanter_trend_analysis: 项目趋势分析
pleasanter_status_summary: 项目状态概要

可用资源

pleasanter://sites: 可用项目列表
pleasanter://users: 用户目录
pleasanter://groups: 组信息
pleasanter://depts: 部门结构
pleasanter://sites/{siteId}/issues: 项目特有的任务
pleasanter://sites/{siteId}/summary: 项目概要
pleasanter://sites/{siteId}/status: 项目状态

可用提示

project_status_report: 生成全面的项目报告
issue_analysis: 分析任务趋势并提供推荐
team_productivity_report: 团队绩效分析
priority_task_identification: 识别紧急任务并制定行动计划
weekly_standup_preparation: 准备每周站立会议信息

开发

开发模式运行

npm run dev

构建

npm run build

测试

npm test

代码检查

npm run lint

故障排除

常见问题

连接失败
- 确认 PLEASANTER_BASE_URL 正确
- 检查 API 密钥的有效性
- 确认网络连接
认证错误
- 确认 API 密钥正确
- 检查用户是否启用了 API 访问
- 确认用户具有必要的权限
速率限制
- 服务器遵循 Pleasanter 的速率限制
- 实现指数退避重试机制
- 监控每日 API 使用量

调试模式

要显示详细日志，请在环境变量中设置 LOG_LEVEL=debug。

Windows 环境特定问题

找不到 WSL 命令
- 确认已安装 Windows Subsystem for Linux (WSL)
- 使用 wsl --version 检查 WSL 版本
路径分隔符问题
- Windows 路径使用反斜杠 \
- 在 JSON 中需要转义：\\
防火墙问题
- 如果 Claude Desktop 无法访问 MCP 服务器
- 可能需要在 Windows Defender 防火墙中允许端口

安全注意事项

请安全地存储 API 密钥
使用环境变量进行配置
实施适当的身份验证和授权
监控 API 使用量
定期轮换密钥

在 WSL2 环境中开发

在 Windows 环境中使用 WSL2 的特殊设置：

1. 在 WSL2 中构建环境

# 在 WSL2 Ubuntu 环境中设置
sudo apt update
sudo apt install nodejs npm

# 设置项目
cd /home/ubuntu/github/Implem.Pleasanter/pleasanter-mcp-server
npm install
npm run build

2. 设置环境变量

# 在 WSL2 环境中设置 Pleasanter
cp .env.example .env

# 编辑 .env 文件
PLEASANTER_BASE_URL=http://10.255.20.80:50001
PLEASANTER_API_KEY=your-api-key-here

3. 从 Windows 侧访问

可以通过 \\wsl.localhost\Ubuntu\ 访问 WSL2 文件系统
Claude Desktop 在 Windows 侧运行，因此需要使用 WSL 命令或 WSL2 路径

在 Docker 环境中运行

构建完整的 Docker 环境

可以构建包含 Pleasanter Web 服务器和 MCP 服务器的完整环境：

# 1. 设置环境变量
cp .env.example .env
# 编辑 .env 文件以设置 Pleasanter API 密钥

# 2. 启动 Docker 环境
docker-compose up -d

# 3. 确认初次设置
docker-compose logs codedefiner

# 4. 访问 Web 应用程序
# 通过 http://localhost:8080 访问 Pleasanter

# 5. 确认 MCP 服务器运行
# 通过 http://localhost:3000 确认 MCP 服务器状态

服务配置

pleasanter-web: Pleasanter Web 应用程序 (端口 8080)
db: PostgreSQL 数据库 (端口 5432)
codedefiner: 数据库初始化 (仅执行一次)
mcp-server: MCP 服务器 (端口 3000)

故障排除

停止和重新启动容器

# 停止所有服务
docker-compose down

# 完全删除包括数据库在内的所有内容
docker-compose down -v

# 重新构建
docker-compose up --build -d

查看日志

# 查看所有服务的日志
docker-compose logs

# 查看特定服务的日志
docker-compose logs pleasanter-web
docker-compose logs mcp-server

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。