Pix MCP 服务器
一个包含模型上下文协议（MCP）服务器的单体仓库，旨在帮助Pix开发者与各种Pix系统和实例进行交互。
全球目标
此仓库提供了一系列MCP服务器，它们通过连接到Pix基础设施、API和服务来扩展IA代理的功能。这些服务器使开发人员能够：
- 自动化工作流程通过IA代理（例如：Claude Code）直接与Pix系统进行交互
- 查询数据在开发环境中即可访问Pix实例的信息，无需离开开发环境
- 简化操作流程在Pix系统上执行常见任务和操作
- 提高生产力通过将Pix服务集成到IA代理中，减少上下文切换
每个MCP服务器都是使用（某种技术或框架）构建的 模型上下文协议SDK 并且遵循Pix编码标准，以确保一致性和可维护性。
建筑学
这个单体仓库遵循模块化架构，其中：
- 每个MCP服务器 是一个独立的软件包，拥有自己的工具和功能
- 共享设施 集中于通用包中以避免重复
- 配置 在所有服务器上实现标准化，便于维护
- 文档 内容全面且遵循一致的模式
仓库结构
pix-mcps/
├── servers/ # Individual MCP servers
│ └── [server-name]/ # Each server in its own directory
├── packages/ # Shared packages
│ └── shared/ # Common utilities and types
├── docs/ # Documentation
│ └── pix-coding-standards.md
├── .nvmrc # Node.js version specification
├── package.json # Root package.json for monorepo
└── README.md # This file先决条件
- Node.js通过……进行管理
.nvmrc文件（使用nvm use（以设置正确的版本） - npm随附 Node.js
- Git用于版本控制
快速入门
1. 克隆并设置
# Clone the repository
git clone
cd pix-mcps
# Use the correct Node.js version
nvm use
# Install dependencies
npm install2. 配置
每个MCP服务器都需要其自身的配置。请复制示例环境文件并进行配置：
cp servers/[server-name]/.env.example servers/[server-name]/.env编辑 .env 附上您的凭证和配置文件。
3. 运行MCP服务器
# Development mode with hot reload
npm run dev --workspace=servers/[server-name]
# Production build
npm run build --workspace=servers/[server-name]可用的MCP服务器
Pix JIRA（pix-jira）
用于与Pix JIRA实例交互的MCP服务器。
特点：
- 获取有关JIRA问题的详细信息
- 查看问题状态、负责人、优先级和元数据
- 访问父级问题、史诗（大型任务）及相关问题
- 查看标签、修复版本和评论
- 支持Pix自定义字段（equipix，appli pix）
可用工具：
get_issue获取完整的JIRA问题详情
发展
创建一个新的MCP服务器
每个MCP服务器应遵循以下结构：
servers/my-server/
├── src/
│ ├── index.ts # Server entry point
│ ├── tools/ # Individual tool implementations
│ │ └── my-tool.ts
│ └── config.ts # Server configuration
├── tests/ # Test files
├── .env.example # Example environment variables
├── package.json # Server dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # Server documentation代码质量
这个单一代码库使用了多种工具来确保代码质量：
- ESLint用于代码检查（或代码规范检查）
- 更漂亮/更整洁（常用于形容代码或格式）用于代码格式化
- TypeScript为了类型安全
- Vitest用于测试
# Run linting
npm run lint
# Fix linting issues
npm run lint:fix
# Format code
npm run format
# Run tests
npm run test
# Type check
npm run typecheck环境变量
所有敏感配置都应存储在 .env 文件并记录在 .env.example 带有占位符的文件。 重要的永远不要放弃（或：永远不要屈服） .env 文件！始终使用 .env.example 用于记录。
使用MCP服务器与Claude代码
配置文件
创建或更新 .mcp.json 在你的项目根目录中，将MCP服务器连接到Claude代码：
{
"mcpServers": {
"pix-jira": {
"command": "npx",
"args": ["-w", "servers/pix-jira", "tsx", "src/index.ts"],
"env": {
"JIRA_BASE_URL": "https://YOURWORKSPACE.atlassian.net",
"JIRA_EMAIL": "${JIRA_EMAIL}",
"JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
}
}
}
}配置完成后，Claude Code 将自动加载 MCP 服务器，并在您的对话中提供其工具。
Docker 配置（备选方案）
为了生产环境使用或更便捷的部署，您可以使用Docker：
{
"mcpServers": {
"pix-jira": {
"command": "docker",
"args": ["exec", "-i", "pix-jira-mcp", "node", "dist/index.js"]
}
}
}请参阅每个服务器的文档，以获取详细的Docker设置说明。
测试
运行测试
# Run all tests
npm test
# Run tests for specific server
npm test --workspace=servers/[server-name]
# Run tests with coverage
npm run test:coverage编写测试
使用 Vitest 进行测试：
import { describe, it, expect } from 'vitest';
import { myTool } from './my-tool';
describe('MyTool', () => {
it('should return expected result', async () => {
const result = await myTool.execute({ id: '123' });
expect(result).toBeDefined();
});
});手动测试和集成测试
📚 书籍 开发者学习收获 - 构建MCP服务器的教训与最佳实践
如需针对特定服务器的测试指南，请参阅各服务器的文档：
文档
可用文档
添加文档
- 记录所有工具及其参数
- 提供使用示例
- 列出所需的环境变量
- 记录错误情况及处理方法
贡献；做出贡献
工作流程
- 创建一个特性分支：
git checkout -b feature/my-feature - 按照编码标准进行修改
- 为你的更改编写测试
- 运行代码检查和测试：
npm run lint && npm test - 使用规范提交进行提交：
git commit -m "feat: add new tool" - 推送并创建一个拉取请求
提交信息格式
跟随 约定式提交（Conventional Commits）：
feat:新功能fix:修复漏洞docs:文档变更test:添加或更新测试refactor:代码重构chore:维护任务
故障排除
常见问题
Node.js版本不匹配
nvm use缺少环境变量
- 检查
.env.example对于所需变量 - 确保
.env文件存在且配置正确
类型错误
npm run typecheckMCP服务器无法启动
- 检查日志中的错误
- 验证环境变量是否已设置
- 确保已安装所有依赖项
资源
许可证
 该软件及其源代码以 AGPL 许可证。
支持
对于问题或疑问：
- 查阅文档中的内容
/docs - 审查现有的MCP服务器实现
- 联系Pix开发团队