MCP GitFlic Server

A fully functional Model Context Protocol (MCP) Server implemented in Kotlin that acts as a gateway to the GitFlic service. The server operates over HTTP (localhost) and provides tools to interact with the GitFlic REST API.

Architecture

This project follows Clean Architecture principles with three main layers:

Domain Layer: Core business models (Project, Commit, Branch, Owner) and repository interfaces
Infrastructure Layer: HTTP client for GitFlic API, MCP protocol handler, and tool implementations
Application Layer: Use cases that orchestrate business logic

The implementation adheres to SOLID principles and uses Test-Driven Development (TDD) practices.

Tech Stack

Language: Kotlin (JVM target: 17)
Build System: Gradle (Kotlin DSL)
HTTP Framework: http4k (Server: Jetty, Client: Apache)
Serialization: Kotlinx.serialization
Testing: JUnit 5, Mockk
Logging: Logback

Prerequisites

JDK 17 or higher
Gradle 7.0 or higher (or use Gradle Wrapper)

Configuration

Environment Variables

The server requires the following environment variables:

GITFLIC_ACCESS_TOKEN (required): Your GitFlic API access token
MCP_SERVER_PORT (optional): Server port (default: 8080)
MCP_SERVER_HOST (optional): Server host (default: localhost)
GITFLIC_BASE_URL (optional): GitFlic API base URL (default: https://api.gitflic.ru)

Setting Environment Variables

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

Building the Project

Using Gradle Wrapper

./gradlew build

Using Gradle directly

gradle build

Running the Server

Using Gradle

./gradlew run

Using the JAR

After building, run the JAR file:

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

The server will start on http://localhost:8080 (or the port specified in MCP_SERVER_PORT).

Adding MCP Server to Claude Code / Cursor

To use this MCP server with Claude Code (or Cursor), you need to configure it in the MCP settings.

Configuration File Location

macOS/Linux:

~/.config/cursor/mcp.json

Windows:

%APPDATA%\Cursor\mcp.json

Configuration Example

Add the following configuration to your mcp.json file:

{
  "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"
      }
    }
  }
}

Alternative: Using HTTP Transport

If you prefer to run the server separately and connect via HTTP:

Start the server manually:

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

Configure in mcp.json:
```
{
  "mcpServers": {
    "gitflic": {
      "url": "http://localhost:8080",
      "transport": "http"
    }
  }
}
```
Note: HTTP transport support may vary depending on your Claude Code/Cursor version. If HTTP transport is not supported, use the command-based configuration above.

Steps to Configure

Build the JAR file:
```
./gradlew build
```
Locate the JAR file:
- Path: build/libs/mcp-gitflic-server-1.0.0.jar
- Use the absolute path in your configuration
Create or edit the MCP configuration file:
- Create mcp.json in the appropriate location (see above)
- Add the configuration as shown above
- Replace /path/to/mcp-gitflic-server with your actual project path
- Replace your-access-token-here with your GitFlic access token
Restart Claude Code / Cursor:
- Close and reopen the application to load the new MCP server configuration
Verify the connection:
- The MCP server should appear in the MCP servers list
- You should be able to use the tools: get_my_projects, get_projects_by_owner, get_project_info, create_project, get_project_commits, get_project_branches

Using the MCP Tools in Claude Code

Once configured, you can use the MCP tools directly in your conversations:

Get your projects: Use the get_my_projects tool
Find projects by owner: Use get_projects_by_owner with the owner alias
Get project details: Use get_project_info with owner and project aliases
Create a project: Use create_project with project details
View commits: Use get_project_commits to see project commit history
List branches: Use get_project_branches to see all project branches

MCP Tools

The server implements the following MCP tools:

get_my_projects: Get a list of projects for the currently authorized user
get_projects_by_owner: Get a list of projects by a specific owner alias (username/organization)
get_project_info: Get detailed information about a specific project
create_project: Create a new project (accepts name, visibility, etc.)
get_project_commits: Get a list of commits for a specific project
get_project_branches: Get a list of branches for a specific project
get_project_issues: Get a list of issues for a specific project
get_issue_details: Get detailed information about a specific issue
create_issue: Create a new issue in a project
edit_issue: Edit an existing issue
delete_issue: Delete an issue from a project
save_file_to_project: Save text content to a file in the project root directory

Testing the Server

Health Check

curl http://localhost:8080/health

Expected response:

{"status":"ok"}

Example Requests

All requests use JSON-RPC 2.0 format over HTTP POST.

1. Get My Projects

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

2. Get Projects by Owner

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. Get Project Info

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. Create Project

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"
    }
  }'

Note: visibility can be PUBLIC or PRIVATE. Default is PUBLIC.

5. Get Project Commits

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. Get Project Branches

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"
    }
  }'

Response Format

Success Response

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

Error Response

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

MCP Error Codes

-32700: Parse error
-32600: Invalid Request
-32601: Method not found
-32602: Invalid params
-32603: Internal error
-32000: Server error

Running Tests

./gradlew test

To see test output:

./gradlew test --info

Project Structure

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

Error Handling

The server handles various error scenarios:

Invalid Access Token: Returns 401 Unauthorized
Project/Owner Not Found: Returns 404 Not Found
Rate Limiting: Returns appropriate error response
Network Errors: Returns server error with details
Invalid Parameters: Returns JSON-RPC invalid params error

Logging

The server uses Logback for logging. Logs are output to the console with the following levels:

INFO: Server startup, request processing
WARN: Invalid requests, parameter validation failures
ERROR: Exceptions, API errors

License

This project is provided as-is for the MCP GitFlic Server implementation.

Contributing

This is a reference implementation following Clean Architecture and SOLID principles. When extending:

Add new tools by implementing the ToolHandler interface
Create corresponding use cases in the application layer
Add repository methods in the domain layer
Implement HTTP client methods in the infrastructure layer
Write comprehensive unit tests

12. Save File to Project

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

Note: The file will be saved in the project root directory. You can also specify subdirectories like "docs/readme.md". The tool automatically creates necessary parent directories and prevents path traversal attacks.

Troubleshooting

Server won't start

Ensure GITFLIC_ACCESS_TOKEN is set
Check that port 8080 (or your configured port) is available
Verify JDK 17+ is installed

API requests failing

Verify your GitFlic access token is valid
Check network connectivity to https://api.gitflic.ru
Review server logs for detailed error messages

Tests failing

Ensure all dependencies are downloaded: ./gradlew build --refresh-dependencies
Check that mockk and JUnit 5 are properly configured

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
gradle/wrapper		gradle/wrapper
src		src
.gitignore		.gitignore
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
settings.gradle.kts		settings.gradle.kts

sandboiii/gitflic-kotlin-mcp

Folders and files

Latest commit

History

Repository files navigation