# ARCLinearGitHub-MCP

[![Swift](https://img.shields.io/badge/Swift-6.0-orange.svg)](https://swift.org)
[![Platforms](https://img.shields.io/badge/Platforms-macOS%2014+-blue.svg)](https://developer.apple.com/macos/)
[![MCP](https://img.shields.io/badge/MCP-2025--11--25-green.svg)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Status](https://img.shields.io/badge/Status-Beta-orange.svg)](#)

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

```bash
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.

```bash
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`:

```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

```swift
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

```bash
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](https://developer.apple.com/documentation/testing). Run
serially because `StubURLProtocol` keeps its handler in static
`OSAllocatedUnfairLock` state:

```bash
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](LICENSE).

## Related

- [Swift MCP SDK](https://github.com/modelcontextprotocol/swift-sdk)
- [ARCKnowledge](https://github.com/arclabs-studio/ARCKnowledge)
- [ARCDevTools](https://github.com/arclabs-studio/ARCDevTools)

---

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