ARCLinearGitHub-MCP

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.

Conventions

• Branches: <type>/<issue-id>-<description>
• Commits: <type>(<scope>): <subject>
• PRs: <Type>/<Issue-ID>: <Title>

Full reference: workflow_get_conventions tool, or ARCMCPValidators.NamingStandards.

License

MIT. See LICENSE.

Related

• Swift MCP SDK
• ARCKnowledge
• ARCDevTools

---

<p align="center">Made with 💛 by ARC Labs Studio</p>