Gitflic Kotlin MCP

MCP GitFlic服务器

功能齐全 模型上下文协议（MCP）服务器 在Kotlin中实现，充当GitFlic服务的网关。服务器通过HTTP（localhost）进行操作，并提供与GitFlic REST API交互的工具。

建筑

该项目如下 整洁架构 原则有三个主要层次：

• 域层：核心商业模式(Project, Commit, Branch, Owner)和存储库接口
• 基础设施层：用于GitFlic API的HTTP客户端、MCP协议处理程序和工具实现
• 应用层：编排业务逻辑的用例

实施坚持 SOLID原则 并使用 测试驱动开发（TDD） 实践。

技术栈

• 语言：Kotlin（JVM目标：17）
• 构建系统：Gradle（Kotlin DSL）
• HTTP框架：http4k（服务器：Jetty，客户端：Apache）
• 序列化：Kotlinx.序列化
• 测试：JUnit5，Mock
• 日志记录：Logback

先决条件

• JDK 17或更高版本
• Gradle 7.0或更高（或使用Gradle Wrapper）

配置

环境变量

服务器需要以下环境变量：

• GITFLIC_ACCESS_TOKEN （必需）：您的GitFlic API访问令牌
• MCP_SERVER_PORT （可选）：服务器端口（默认：8080）
• MCP_SERVER_HOST （可选）：服务器主机（默认：localhost）
• GITFLIC_BASE_URL （可选）：GitFlic API基础URL（默认值：https://api.gitflic.ru)

设置环境变量

Linux/macOS：

export GITFLIC_ACCESS_TOKEN="your-access-token-here"
export MCP_SERVER_PORT=8080

Windows（PowerShell）：

$env:GITFLIC_ACCESS_TOKEN="your-access-token-here"
$env:MCP_SERVER_PORT=8080

Windows（CMD）：

set GITFLIC_ACCESS_TOKEN=your-access-token-here
set MCP_SERVER_PORT=8080

建设项目

使用Gradle包装

./gradlew build

直接使用Gradle

gradle build

运行服务器

使用Gradle

./gradlew run

使用JAR

构建后，运行JAR文件：

./gradlew build
java -jar build/libs/mcp-gitflic-server-1.0.0.jar

服务器将于启动 http://localhost:8080 （或中指定的端口 MCP_SERVER_PORT).

将MCP服务器添加到Claude代码/游标

要将此MCP服务器与Claude Code（或Cursor）一起使用，您需要在MCP设置中对其进行配置。

配置文件位置

macOS/Linux：

~/.config/cursor/mcp.json

窗户：

%APPDATA%\Cursor\mcp.json

配置示例

将以下配置添加到您的 mcp.json 文件：

{
  "mcpServers": {
    "gitflic": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/mcp-gitflic-server/build/libs/mcp-gitflic-server-1.0.0.jar"
      ],
      "env": {
        "GITFLIC_ACCESS_TOKEN": "your-access-token-here",
        "MCP_SERVER_PORT": "8080",
        "MCP_SERVER_HOST": "localhost"
      }
    }
  }
}

替代方案：使用HTTP传输

如果您希望单独运行服务器并通过HTTP连接：

1. 手动启动服务器：

   export GITFLIC_ACCESS_TOKEN="your-access-token-here"
   ./gradlew run

1. 在中配置 mcp.json:

   {
     "mcpServers": {
       "gitflic": {
         "url": "http://localhost:8080",
         "transport": "http"
       }
     }
   }

备注：HTTP传输支持可能因您的Claude Code/Coursor版本而异。如果不支持HTTP传输，请使用上述基于命令的配置。

配置步骤

1. 构建JAR文件：

   ./gradlew build

1. 找到JAR文件：

- 路径： build/libs/mcp-gitflic-server-1.0.0.jar - 在配置中使用绝对路径

1. 创建或编辑MCP配置文件：

- 创建 mcp.json 在适当的位置（见上文） - 添加如上所示的配置 - 替换 /path/to/mcp-gitflic-server 使用您的实际项目路径 - 替换 your-access-token-here 使用您的GitFlic访问令牌

1. 重新启动克劳德代码/光标：

- 关闭并重新打开应用程序以加载新的MCP服务器配置

1. 验证连接：

- MCP服务器应出现在MCP服务器列表中 - 您应该能够使用这些工具： get_my_projects, get_projects_by_owner, get_project_info, create_project, get_project_commits, get_project_branches

在Claude代码中使用MCP工具

配置后，您可以在对话中直接使用MCP工具：

• 获取您的项目：使用 get_my_projects 工具
• 按所有者查找项目：使用 get_projects_by_owner 所有者别名
• 获取项目详细信息：使用 get_project_info 具有所有者和项目别名
• 创建项目：使用 create_project 包含项目详细信息
• 查看提交：使用 get_project_commits 查看项目提交历史记录
• 列出分支：使用 get_project_branches 查看所有项目分支

MCP工具

服务器实现了以下MCP工具：

1. get_my_projects：获取当前授权用户的项目列表
2. get_projects_by_owner：按特定所有者别名（用户名/组织）获取项目列表
3. get_project_info：获取特定项目的详细信息
4. create_project：创建新项目（接受名称、可见性等）
5. get_project_commits：获取特定项目的提交列表
6. get_project_branches：获取特定项目的分支列表
7. get_project_issues：获取特定项目的问题列表
8. get_issue_details：获取有关特定问题的详细信息
9. create_issue：在项目中创建新问题
10. edit_issue：编辑现有问题
11. delete_issue：从项目中删除问题
12. save_file_to_project：将文本内容保存到项目根目录中的文件

测试服务器

健康检查

curl http://localhost:8080/health

预期响应：

{"status":"ok"}

请求示例

所有请求都通过HTTP POST使用JSON-RPC 2.0格式。

1.获取我的项目

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "get_my_projects",
    "params": {}
  }'

2.按所有者获取项目

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "get_projects_by_owner",
    "params": {
      "ownerAlias": "username"
    }
  }'

3.获取项目信息

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "get_project_info",
    "params": {
      "ownerAlias": "username",
      "projectAlias": "project-name"
    }
  }'

4.创建项目

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "create_project",
    "params": {
      "name": "My New Project",
      "alias": "my-new-project",
      "description": "Project description",
      "visibility": "PUBLIC"
    }
  }'

备注: visibility 可以是 PUBLIC 或 PRIVATE默认值为 PUBLIC.

5.获取项目提交

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "5",
    "method": "get_project_commits",
    "params": {
      "ownerAlias": "username",
      "projectAlias": "project-name"
    }
  }'

6.获取项目分支

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "6",
    "method": "get_project_branches",
    "params": {
      "ownerAlias": "username",
      "projectAlias": "project-name"
    }
  }'

响应格式

成功响应

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": "[{\"id\":1,\"alias\":\"project\",\"name\":\"Project Name\"}]",
  "error": null
}

错误响应

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": null,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": null
  }
}

MCP错误代码

• -32700：分析错误
• -32600：无效请求
• -32601：未找到方法
• -32602：无效参数
• -32603：内部错误
• -32000：服务器错误

运行测试

./gradlew test

要查看测试输出：

./gradlew test --info

项目结构

mcp-gitflic-server/
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
├── README.md
└── src/
    ├── main/
    │   ├── kotlin/com/gitflic/mcp/
    │   │   ├── domain/              # Domain models and interfaces
    │   │   ├── infrastructure/      # HTTP client, MCP protocol, tools
    │   │   └── application/         # Use cases and main entry point
    │   └── resources/
    │       └── application.conf
    └── test/
        └── kotlin/com/gitflic/mcp/  # Unit tests

错误处理

服务器处理各种错误情况：

• 访问令牌无效：返回401未经授权
• 未找到项目/所有者：返回404未找到
• 速率限制：返回适当的错误响应
• 网络错误：返回服务器错误及其详细信息
• 无效参数：返回JSON-RPC无效参数错误

日志记录

服务器使用Logback进行日志记录。日志以以下级别输出到控制台：

• 信息：服务器启动，请求处理
• 警告：无效请求，参数验证失败
• 错误：异常，API错误

许可证

此项目按原样提供，用于MCP GitFlic服务器实现。

贡献

这是一个遵循清洁架构和SOLID原则的参考实现。延伸时：

1. 通过实施 ToolHandler 接口
2. 在应用层创建相应的用例
3. 在域层中添加存储库方法
4. 在基础架构层实现HTTP客户端方法
5. 编写全面的单元测试

12.将文件保存到项目

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "12",
    "method": "save_file_to_project",
    "params": {
      "fileName": "notes.txt",
      "content": "This is a sample file content.\nIt can contain multiple lines.\n\nCreated via MCP tool."
    }
  }'

备注：文件将保存在项目根目录中。您还可以指定子目录，如 "docs/readme.md"。该工具会自动创建必要的父目录并防止路径遍历攻击。

故障排除

服务器无法启动

• 确保 GITFLIC_ACCESS_TOKEN 已设置
• 检查端口8080（或您配置的端口）是否可用
• 验证是否已安装JDK 17+

API请求失败

• 验证您的GitFlic访问令牌是否有效
• 检查网络连接 https://api.gitflic.ru
• 查看服务器日志以了解详细的错误消息

测试失败

• 确保所有依赖项都已下载： ./gradlew build --refresh-dependencies
• 检查mockk和JUnit5是否配置正确