Clartat MCP

Clartat MCP服务器

🔍 使用GitHub Copilot在VS代码中直接分析GitHub Projects v2

一个模型上下文协议（MCP）服务器，将您的GitHub项目数据带入GitHub Copilot Chat。

______________________________________________________________________

🚀 快速开始

步骤1：构建服务器

sbt assembly

这创造了 target/scala-3.7.3/clartat-mcp.jar

第二步：获取GitHub代币

1. 首选https://github.com/settings/tokens
2. 点击 “生成新令牌（经典）”
3. 命名它（例如，“Clartat MCP”）
4. 选择这些范围：

- ✅ repo - ✅ read:org - ✅ read:project

1. 点击 “生成令牌” 和 立即复制 （你不会再看到它了！）

步骤3：找到您的项目编号

您的GitHub项目URL如下：

https://github.com/orgs/YOUR_ORG/projects/1
                        ^^^^^^^^          ^
                        your org          project number

步骤4：配置VS代码

创建 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "clartat": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/clartat-mcp.jar"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxx",
        "GITHUB_OWNER": "YourOrganization",
        "GITHUB_REPO": "1"
      }
    }
  }
}

替换：

• /absolute/path/to/clartat-mcp.jar → JAR的实际路径
• ghp_xxxxxxxxxxxxx → 您的GitHub令牌
• YourOrganization → 您的GitHub组织名称
• 1 → 您的项目编号

步骤5：激活服务器

1. 按 Ctrl+Shift+P （或 Cmd+Shift+P 在Mac上）
2. 类型 “开发人员：重新加载窗口”
3. 按 Enter

第六步：使用它！

打开GitHub Copilot Chat并使用可用工具：

查看项目问题

• “显示项目中的所有问题”
• “有哪些悬而未决的问题？”
• “总结项目状态”

这 github-project 该工具将从您的GitHub项目中获取所有数据！

创建新问题

• “创建一个问题：'实现身份验证'，大小为M，优先级为P2”
• “添加工单：'修复登录错误'优先级P0”
• “创建问题‘添加暗模式’大小L优先级P3”

这 create-github-issue 工具将：

• ✅ 在存储库中创建问题
• ✅ 自动将其添加到项目中
• ✅ 设置大小和优先级自定义字段

______________________________________________________________________

📋 可用工具

1. github-project -查看项目项

从GitHub项目中获取并显示所有项目。

您将获得：

• ✅ 所有项目 （问题、草案问题、拉取请求）
• ✅ 完整的问题详细信息 （标题、描述、状态、URL）
• ✅ 存储库信息 对于每个项目
• ✅ 自定义项目字段 （状态、优先级、大小等）
• ✅ 完整JSON数据 用于高级分析

输出示例：

# GitHub Project Items

**Organization**: MyOrg
**Project Number**: 1
**Total Items**: 32
**Issues**: 30

## Issues

### #4: Create User Authentication
**State**: OPEN
**URL**: https://github.com/MyOrg/my-repo/issues/4
**Repository**: MyOrg/my-repo

Implement OAuth 2.0 authentication flow...

2. create-github-issue -创建项目问题

创建一个新的GitHub问题，并使用自定义字段自动将其添加到您的项目中。

参数：

• 标题 （必填）：发行标题
• 身体 （可选）：问题描述
• 尺寸 （可选）：发行量- XS, S, M, L，或 XL
• 优先级 （可选）：问题优先级- P0, P1, P2, P3, P4，或 P5

它的作用：

1. 在与项目关联的存储库中创建问题
2. 自动将其添加到您的GitHub项目中
3. 设置“大小”和“优先级”自定义字段（如果提供）

要求：

• 您的GitHub项目必须具有名为“大小”和“优先级”的自定义字段（不区分大小写）
• 尺寸字段：单选，可选XS、S、M、L、XL
• 优先级字段：单选，选项P0、P1、P2、P3、P4、P5

可选配置： 添加 GITHUB_REPO_NAME 如果您的项目为空，请发送到您的环境：

{
  "env": {
    "GITHUB_TOKEN": "...",
    "GITHUB_OWNER": "...",
    "GITHUB_REPO": "1",
    "GITHUB_REPO_NAME": "my-repo"
  }
}

输出示例：

✅ Issue Created Successfully

**Repository**: MyOrg/my-repo
**Issue Number**: #42
**Title**: Implement OAuth authentication
**URL**: https://github.com/MyOrg/my-repo/issues/42
✅ **Added to Project**
**Size**: M
**Priority**: P2

## Description
Add OAuth 2.0 support for user authentication

______________________________________________________________________

🔒 安全

⚠️ 重要提示：

• 永不承诺 .vscode/mcp.json 用你的代币
• 添加到 .gitignore:

  echo ".vscode/mcp.json" >> .gitignore

• 定期旋转令牌
• 使用最小范围（只使用需要的范围）

______________________________________________________________________

🐛 故障排除

工具未在副驾驶中显示？

1. 检查JAR路径是否 绝对的 （非相对）
2. 重新加载VS代码： Ctrl+Shift+P → “开发人员：重新加载窗口”
3. 检查VS代码输出： View → Output → 选择 MCP

身份验证错误？

• 验证令牌是否具有 repo, read:org, read:project 范围
• 支票令牌尚未过期
• 确保 GITHUB_TOKEN 设置正确

未找到项目？

• GITHUB_OWNER 必须是 精确 组织名称
• GITHUB_REPO 必须只是 数字 （例如，“1”，而不是“我的项目”）
• 确保您的令牌可以访问该组织

______________________________________________________________________

🛠️ 发展

构建与测试

# Compile
sbt compile

# Create JAR
sbt assembly

# Run tests
sbt test

手动测试

# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  java -jar target/scala-3.7.3/clartat-mcp.jar | jq '.'

______________________________________________________________________

📁 项目结构

src/main/scala/com/clartat/mcp/
├── McpServerApp.scala                    # Entry point
├── client/
│   └── GithubGraphQLClient.scala        # GitHub GraphQL API
├── domain/
│   ├── JsonRpc.scala                    # JSON-RPC models
│   ├── McpProtocol.scala                # MCP models
│   ├── Tool.scala                       # Tool models
│   └── github/ProjectV2.scala           # GitHub models
├── protocol/
│   ├── JsonRpcProtocol.scala            # JSON-RPC protocol
│   └── McpProtocol.scala                # MCP protocol
├── service/
│   ├── McpRequestHandler.scala          # Request handling
│   └── McpServerIO.scala                # I/O (stdin/stdout)
└── tools/
    ├── Tool.scala                       # Tool base trait
    ├── ToolRegistry.scala               # Tool registry
    ├── DefaultTools.scala               # Tool configuration
    └── impl/GithubProjectV2Tool.scala   # GitHub tool

架构：

• 清洁分离 域、协议、服务和工具之间
• 可扩展 基于注册表模式的工具系统
• 类型安全 Scala 3和Circe用于JSON

______________________________________________________________________

📝 许可证

MIT许可证-有关详细信息，请参阅许可证文件

______________________________________________________________________

🤝 贡献

欢迎投稿！请随意：

• 报告错误
• 建议功能
• 提交拉取请求

______________________________________________________________________

由以下材料制成❤️ 使用Scala 3和模型上下文协议