Pleasanter MCP Server

Pleasanter MCP 服务器

Implem.Pleasanter整合Model Context Protocol (MCP)服务器。AI我的助手Pleasanter的明细栏样式中定义的设置。

机能

工具

• 课题管理：创建、读取、更新和删除课题
• 高级搜索：在整个项目中进行复杂的过滤和搜索
• 分析机能：趋势分析和项目状态摘要
• 批量操作：高效批量处理多个问题

资源

• 站点：可用Pleasanter访问项目
• 用户/组/部门：组织构造情报
• 动态资源：实时项目状态和挑战数据

提示

• 项目状态报告：自动化项目运行状况报告
• 课题分析：趋势分析和记录
• 团队工作效率：性能分析和洞察
• 确定优先任务：确定紧急任务和行动计划
• 每周安装准备：准备小组会议

安装

1. 克隆或下载服务器代码

   cd pleasanter-mcp-server

1. 安装相关性

   npm install

1. 构建服务器

   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

设定

1. 创建环境文件

   cp .env.example .env

1. 编辑设置

   # 必須設定
   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请安全管理钥匙，定期轮换

1. Pleasanter API获取密钥

- Pleasanter登录系统 - 转到用户设置 - API生成或复制密钥 - 按帐户API确认已启用访问

Claude Desktop使用方法

macOS環境

1. 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环境

1. 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://10.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环境

1. 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"
         }
       }
     }
   }

1. Claude Desktop重新启动

1. 确认连接

Claude Desktop单击功能区上的MCP请确保服务器工作正常：

步骤1:基本连接确认

   利用可能なPleasanterサイトを一覧表示できますか？

预期结果：显示站点列表或显示相应的错误消息

步骤2:资源确认

   利用可能なPleasanterリソースにはどのようなものがありますか？

预期结果: pleasanter://sites、pleasanter://users等资源一览

步骤3:工具确认

   Pleasanter関連で利用できるツールや機能を教えてください。

预期结果: pleasanter_create_issue、pleasanter_get_issues等工具一览显示

步骤4:确认用户信息

   Pleasanterのユーザー一覧を最初の5件だけ取得してください。

预期结果: 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

故障排除

常见问题

1. 接続失败

- PLEASANTER_BASE_URL确认是否正确 - API检查密钥的有效性 - 检查网络连接

1. 验证错误

- API验证密钥是否正确 - 用户的API检查访问是否有效 - 确保用户具有所需的权限

1. 汇率限制

- 服务器是Pleasanter的汇率限制 - 重试实现指数退避 - 日次のAPI使用量を監視

调试模式

要查看详细日志，请使用环境变量 LOG_LEVEL=debug 中所述修改相应参数的值。

视窗環境固有の問題

1. WSL缺少命令

- Windows Subsystem for Linux (WSL)确认是否已安装 - wsl --version 单击功能区上WSL确认的版本

1. 路径分隔符问题

- Windows的路径是反斜线 \ 使用 - JSON中需要转义： \\

1. 防火墙问题

- 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从侧面访问

• WSL2的文件系统 \\wsl.localhost\Ubuntu\ 可访问
• 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应用程序（端口8080）
• 数据库: PostgreSQL数据库（端口5432）
• 代码定义器：用于数据库初始化（仅执行一次）
• mcp服务器: 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请参见文件。