MCP 服务器

ARCLinearGitHub-MCP

Bridges Linear issue tracking and GitHub repository management with ARC naming conventions, enabling composite workflows like creating a Linear issue and GitHub branch in one step.

README

ARCLinearGitHub-MCP

Native Swift Model Context Protocol (MCP) server that bridges Linear (issue tracking) and GitHub (repository management), enforces ARC Labs naming conventions, and exposes 21 tools to Claude Code over stdio.

Multi-workspace — talk to several Linear workspaces from one binary via LINEAR_WORKSPACES.
Convention enforcement — branch, commit and PR validators with byte-compatible regex ported from the Python reference implementation.
Composite workflows — workflow_start_feature creates the Linear issue and the GitHub branch in a single round-trip.
Swift 6 + strict concurrency — every public type is Sendable, the data layer uses actors, no force-unwraps and no nonisolated(unsafe).

This is the Swift rewrite of the original Python LinearGitHub-MCP. The wire format is identical (same tool names, same request/response shape), so existing Claude Code configurations only need a binary-path swap.

Overview

ARCLinearGitHub-MCP is a Swift Package laid out following the microapps SPM pattern (Majid Jabrayilov) and ARC Clean Architecture:

Sources/
├── ARCMCPModels         Foundation — entities + error types
├── ARCMCPNetworking     Foundation — URLSession HTTP + retry policy
├── ARCMCPValidators     Foundation — branch + commit validators
├── ARCMCPLinear         Data       — GraphQL client + workspace registry
├── ARCMCPGitHub         Data       — REST client
├── ARCMCPCore           Orchestration — AppDependencies + MCP tools
├── ARCMCPMocks          Tests      — StubURLProtocol + AppDependencies.mock
└── arc-mcp              Executable — stdio MCP server

The 21 MCP tools live in ARCMCPCore/Tools/. Each handler decodes its arguments via ArgumentAccess, calls one or more closures on AppDependencies, then maps the entities back into the Python-compatible {success: bool, ...} envelope via Mappers.

Requirements

macOS 14 Sonoma or later
Swift 6.0 toolchain (Xcode 16+)
Linear API token and GitHub Personal Access Token

Installation

git clone https://github.com/arclabs-studio/ARCLinearGitHub-MCP.git
cd ARCLinearGitHub-MCP
make build-release

The binary lands at .build/release/arc-mcp.

Configuration

Every setting is read from the process environment.

export GITHUB_TOKEN=ghp_xxx
export GITHUB_ORG=arclabs-studio
export DEFAULT_PROJECT=PLAT
export DEFAULT_REPO=MyApp

# single-workspace
export LINEAR_API_KEY=lin_api_xxx

# or multi-workspace
export LINEAR_WORKSPACES='{"ios":"lin_api_a","backend":"lin_api_b"}'

Optional overrides: LINEAR_API_URL, GITHUB_API_URL, REQUEST_TIMEOUT.

Usage

Claude Code

Add the binary to ~/.claude/mcp-servers.json:

{
  "mcpServers": {
    "arc-linear-github": {
      "command": "/abs/path/.build/release/arc-mcp"
    }
  }
}

Restart Claude Code. /mcp lists 21 tools under arc-linear-github.

Programmatic embedding

import ARCMCPCore
import MCP

let settings = try Settings.fromEnvironment()
let server = Server(name: "my-mcp", version: "1.0.0",
                    capabilities: .init(tools: .init(listChanged: false)))
await ToolRegistry.register(on: server, dependencies: .production(settings: settings))
try await server.start(transport: StdioTransport())
await server.waitUntilCompleted()

Development

make lint        # SwiftLint
make format      # SwiftFormat (dry-run)
make fix         # Apply SwiftFormat
make build       # debug build
make test        # swift test --no-parallel (StubURLProtocol uses shared state)
make coverage    # tests with code coverage
make docs        # DocC archive for ARCMCPCore
make run         # build-release && exec arc-mcp

Project layout

Target	Purpose
`ARCMCPModels`	Codable `Sendable` Linear and GitHub entities + `MCPDomainError`
`ARCMCPNetworking`	`HTTPClient` actor, `RetryPolicy`, `HTTPError`
`ARCMCPValidators`	Pure branch + commit validators with ARC regex
`ARCMCPLinear`	GraphQL client + multi-workspace registry
`ARCMCPGitHub`	REST client + endpoint enum
`ARCMCPCore`	`AppDependencies`, MCP tool registry, mappers
`ARCMCPMocks`	`StubURLProtocol` + `AppDependencies.mock` for tests
`arc-mcp`	`@main` stdio executable

Testing

Swift Testing. Run serially because StubURLProtocol keeps its handler in static OSAllocatedUnfairLock state:

swift test --no-parallel

Tests are organised per target:

ARCMCPModelsTests — Codable round-trip for every entity.
ARCMCPNetworkingTests — retry semantics with stubbed URLSession.
ARCMCPValidatorsTests — every case ported from tests/test_validators/.
ARCMCPLinearTests / ARCMCPGitHubTests — URLProtocol stubs + fixture JSON.
ARCMCPCoreTests — Settings env parsing + tool registry dispatch.

Architecture

Clean Architecture — Domain (ARCMCPModels, *Validators), Data (*Linear, *GitHub), Orchestration (ARCMCPCore).
Microapps SPM — one library target per concern, layered by build dependency.
Closure-based DI — every capability is a @Sendable async closure on AppDependencies. production(settings:) wires real actors; .mock (in ARCMCPMocks) returns canned values.
Strict concurrency — Swift 6 .v6 language mode across every target.