Linear MCP Service Gateway (Go Implementation)

This is a specialized Model Context Protocol (MCP) server, implemented in the Go programming language, designed to abstract and streamline operations against the Linear API.

Core Capabilities

• Provisioning, modification, and querying of Linear tickets (issues).
• Fetching assignment details for personnel.
• Appending commentary to existing issues.
• Obtaining organizational team metadata.
• Intelligent throttling mechanisms to adhere strictly to Linear API consumption quotas.

Dependencies & Requirements

• Go runtime environment, version 1.23 or newer.
• A valid authentication token for the Linear API.

Acquisition Methods

Pre-compiled Binaries

Executable packages for major operating systems (Linux, macOS, Windows) are available on the official GitHub release repository.

1. Obtain the package specific to your operating environment.
2. Grant execute permissions (for Unix-like systems):

bash chmod +x linear-mcp-go-*

1. Execute the binary according to the usage instructions below.

Automated Retrieval

A script to fetch the latest version automatically for Linux environments:

bash

Fetch details for the most recent release

RELEASE=$(curl -s https://api.github.com/repos/geropl/linear-mcp-go/releases/latest) DOWNLOAD_URL=$(echo $RELEASE | jq -r '.assets[] | select(.name | contains("linux")) | .browser_download_url') curl -L -o ./linear-mcp-go $DOWNLOAD_URL chmod +x ./linear-mcp-go

Configure the MCP server for an assistant (e.g., Cline)

./linear-mcp-go setup --tool=cline

Operational Guidance

Version Verification

Confirm the running version of the Linear MCP gateway:

bash ./linear-mcp-go version

This command outputs build metadata, including the version identifier, Git SHA, and compilation timestamp.

Initiating the Gateway

1. Set the requisite API credential as an environment variable:

bash export LINEAR_API_KEY=your_linear_api_key

1. Launch the server process:

bash

Default operation: read-only mode

./linear-mcp-go serve

Enable read/write capabilities

./linear-mcp-go serve --write-access

The service will commence listening for incoming MCP communication streams via standard input/output (stdin/stdout).

Setup for AI Entities

The setup utility streamlines configuration across various AI agents:

bash

Pre-requisite: API Key must be exported (Ona is an exception)

export LINEAR_API_KEY=your_linear_api_key

Default setup for Cline

./linear-mcp-go setup

Setup permitting write operations

./linear-mcp-go setup --write-access

Automatically sanction read-only tools

./linear-mcp-go setup --auto-approve=allow-read-only

Specify precise tools for automatic authorization

./linear-mcp-go setup --auto-approve=linear_get_issue,linear_search_issues

Combined setup: Write access plus read-only tool sanctioning

./linear-mcp-go setup --write-access --auto-approve=allow-read-only

Configure for a different target entity (currently only 'cline' is supported)

./linear-mcp-go setup --tool=cline

This command sequence performs: 1. Installation status check for the Linear MCP binary. 2. Deployment of the executable to the designated system path if necessary. 3. Configuration scripting for the target AI agent. 4. Implementation of auto-approval policies for specified functions.

The --auto-approve flag governs which functions are permitted execution without explicit user confirmation during an AI interaction: - --auto-approve=allow-read-only: Authorizes all non-mutating functions (linear_search_issues, linear_get_user_issues, linear_get_issue, linear_get_teams). - --auto-approve=tool_a,tool_b,...: A comma-delimited list of explicitly authorized functions.

By default, the service operates in a restricted, read-only mode, disabling mutation tools: - linear_create_issue - linear_update_issue - linear_add_comment

These write functions require the --write-access=true argument upon server launch to become active.

Operational Toolset Definitions

linear_create_issue

Instantiates a novel Linear issue, capable of defining hierarchical relationships (sub-issues) and applying metadata tags.

Arguments: - title (Mandatory): The subject line of the new ticket. - team (Mandatory): The organizational unit identifier (via key, UUID, or name). - description: Detailed problem statement or task description. - priority: Numerical importance ranking (scale 0 to 4). - status: Initial state of the issue. - parentIssue: ID of the parent issue, if this is a subordinate task. - labels: List of label identifiers, provided as a delimited string.

linear_update_issue

Modifies the attributes of an existing Linear ticket.

Arguments: - id (Mandatory): Unique identifier of the issue to alter. - title: Replacement title. - description: Revised description content. - priority: New priority setting (0-4). - status: New state assignment.

linear_search_issues

Executes sophisticated, flexible queries against the issue database.

Arguments: - query: Text string to search within titles and descriptions. - teamId: Constrain results to a specific team identifier. - status: Filter by the issue's current lifecycle stage (e.g., 'In Progress', 'Done'). - assigneeId: Filter based on the assigned user's ID. - labels: Filter using a comma-separated list of required label names. - priority: Filter by priority level (1=Urgent, 2=High, 3=Normal, 4=Low). - estimate: Filter based on assigned story points/estimate. - includeArchived: Boolean flag to include deprecated issues (default: disabled). - limit: Upper bound on the number of records returned (default: 10).

linear_get_user_issues

Fetches the list of issues currently allocated to a specific user or the token owner.

Arguments: - userId: Optional identifier for a specific user. If omitted, targets the authenticated principal. - includeArchived: Boolean flag to include archived items. - limit: Maximum quantity of issues to retrieve (default: 50).

linear_get_issue

Retrieves the complete data record for a single issue via its unique identifier.

Arguments: - issueId (Mandatory): The specific ID of the target issue.

linear_add_comment

Inserts a new commentary entry onto a designated issue.

Arguments: - issueId (Mandatory): Identifier of the issue receiving the comment. - body (Mandatory): The message content, formatted using Markdown. - createAsUser: Alternate display name for the commentator. - displayIconUrl: Custom avatar URL to associate with the comment.

linear_get_teams

Returns a directory of organizational teams, optionally filtered by name substring.

Arguments: - name: A partial string match to filter the returned team collection.

Quality Assurance (Testing)

Testing relies on the go-vcr framework, executing against the staging environment https://linear.app/linear-mcp-go-test.

Standard Test Execution

Run all existing recorded interactions (cassettes): bash go test -v ./...

Regenerating Test Recordings:

Requires a valid LINEAR_API_KEY.

bash go test -v -record=true ./...

This updates all tests that do not result in permanent remote state changes.

bash go test -v -recordWrites=true ./...

This re-runs all tests, including state-modifying ones, which may necessitate manual cleanup post-execution.

bash go test -v -golden=true ./...

Updates all serialized golden files.

Publication Cycle

The project leverages GitHub Actions for continuous integration, testing, and artifact generation. The definitive version is codified in the ServerVersion constant within pkg/server/server.go.

Automated Build and CI

1. All commits to the main branch and incoming pull requests trigger automated validation.
2. Pushing a tag conforming to the v* pattern (e.g., v2.0.0) initiates an automated release process.
3. Binaries for all target platforms (Linux, macOS, Windows) are compiled, embedding build metadata (commit hash and timestamp).

Manual Release Procedure

Crucial: Version tag creation must only occur on the main branch after all intended modifications are finalized and merged.

1. Version Increment: Update the ServerVersion constant in pkg/server/server.go go // ServerVersion denotes the current release of the MCP gateway ServerVersion = "1.14.0"

2. Review Submission: Submit the version change as a pull request for scrutiny and testing.

3. Integration: Upon approval and merge into main.

4. Tag Creation and Push: bash # Ensure local repository is synchronized git checkout main git pull origin main

# Create and transmit the tag matching the server.go constant git tag v1.14.0 git push origin v1.14.0

1. Automation: The associated GitHub Workflow will autonomously handle:
2. Building platform-specific binaries, embedding version data.
3. Establishing a formal GitHub release corresponding to the tag.
4. Attaching the compiled executables to the release artifact list.

Version Reporting

The version command furnishes: - Release Tag: Derived from the ServerVersion constant in pkg/server/server.go. - Source Revision: The Git commit SHA, embedded during compilation. - Build Time: Timestamp of the compilation process.

Development builds where source control information is unavailable will show 'unknown' for revision and timestamp.

Licensing

MIT

Reference: XMLHttpRequest (XHR) Overview

XMLHttpRequest (XHR) is an interface provided as a JavaScript object, facilitating the transmission of HTTP requests from a web client to a server. This API enables browser-based applications to request server resources asynchronously following initial page load, and subsequently process the received data. XHR is fundamental to the concept of Asynchronous JavaScript and XML (Ajax). Before Ajax, interaction with a server typically necessitated full page refreshes triggered by form submissions or direct hyperlink navigation.

== Historical Context == The foundational idea for XMLHttpRequest originated in the year 2000, developed by engineers working on Microsoft Outlook. This concept was first materialized within the Internet Explorer 5 browser release (1999). Curiously, the initial implementation did not use the standardized XMLHttpRequest string; instead, developers invoked object creation via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), universal support for the XMLHttpRequest identifier was achieved across all major browsers, following adoption by Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial specification draft for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft for Level 2 followed on February 25, 2008, introducing capabilities for event progress monitoring, enabling cross-site communication, and managing raw byte streams. By the close of 2011, the Level 2 features were integrated back into the primary specification. Development stewardship transitioned to the WHATWG near the end of 2012, where it is currently maintained as a dynamic document utilizing Web IDL.

== Operational Steps == Programmatically, invoking an XMLHttpRequest typically requires a sequence of operations:

1. Instantiation: Create an instance of the XMLHttpRequest object using its constructor.
2. Configuration: Invoke the open() method to define the HTTP verb, target URL, and whether the operation should be synchronous or asynchronous.
3. Asynchronous Handling: For non-blocking requests, attach an event handler function (listener) to be executed upon state transitions.
4. Transmission: Start the request by calling the send() method, optionally passing payload data.
5. Response Processing: Monitor the listener for state changes. Upon reaching state 4 (the 'done' state), the server response is typically available in the responseText property.

Beyond these fundamental steps, XHR offers granular control over request mechanics. Custom HTTP headers can be injected to guide server processing. Data can be uploaded via the argument to send(). Responses can be automatically parsed from JSON into native JavaScript objects or processed incrementally as data streams arrive. Furthermore, requests can be forcibly terminated or configured with a timeout threshold.

== Cross-Origin Communication ==

During the nascent stages of the World Wide Web, limitations were recognized regarding interaction betw