mcp protocol translation to linear graphql
Translates Model Context Protocol (MCP) tool calls received over stdio into authenticated GraphQL requests against the Linear API. The MCP Server Layer (src/mcp-server.ts) receives CallTool requests, routes them through a type-guarded tool dispatch system (src/tools/type-guards.ts validates arguments against Zod schemas), and delegates to LinearService which wraps @linear/sdk's LinearClient. This three-layer architecture decouples protocol handling from Linear SDK details, enabling AI clients (Cursor, Claude Desktop, Claude VSCode, GoMCP) to interact with Linear without custom integration code.
Unique: Three-layer architecture (MCP → Tool Dispatch → Linear Service) with strict separation of concerns: MCP protocol handling is isolated in src/mcp-server.ts, tool schemas and handlers are separated in src/tools/, and all Linear SDK access is funneled through a single LinearService class. This design enables adding new tools without touching protocol code and makes the codebase testable at each layer.
vs alternatives: Cleaner than custom REST API wrappers because it uses standard MCP protocol, reducing client-side integration work; more maintainable than monolithic Linear API clients because tool dispatch is schema-driven and handlers are decoupled from protocol details.
schema-driven tool registration and dispatch
Registers 42 Linear tools (organized by domain: Issues, Projects, Initiatives, Cycles, Teams, Users/Org) via Zod schemas defined in src/tools/definitions/. Each tool has a corresponding handler in src/tools/handlers/ that receives validated arguments. The dispatch system uses type guards (src/tools/type-guards.ts) to validate incoming arguments against schemas before routing to handlers. Tool names follow a consistent linear_* prefix convention. This schema-first approach enables runtime validation, auto-documentation, and safe argument passing without manual type coercion.
Unique: Uses Zod schemas as the single source of truth for tool contracts — schemas define both validation rules and MCP tool descriptions, eliminating duplication. Type guards in src/tools/type-guards.ts enforce schema compliance before handler execution, preventing invalid data from reaching the Linear SDK.
vs alternatives: More robust than string-based argument parsing because Zod provides compile-time type safety and runtime validation; more maintainable than hand-written validators because schema changes automatically update both validation and documentation.
issue lifecycle management (create, read, update, delete, search)
Exposes 18 issue-related tools covering the full lifecycle: create_issue, update_issue, delete_issue, get_issue, list_issues, search_issues, add_issue_comment, update_issue_comment, delete_issue_comment, and others. Each tool translates to a GraphQL operation via LinearService, which calls @linear/sdk's LinearClient. Handlers support filtering by status, assignee, project, cycle, and custom fields. The search_issues tool enables semantic and keyword-based queries. Comment operations support markdown formatting and attachment handling.
Unique: Issue tools are organized by operation type (create, update, delete, search, comment) with separate handlers for each, enabling fine-grained permission control and error handling. The search_issues tool integrates Linear's native search API rather than implementing custom indexing, reducing maintenance burden.
vs alternatives: More comprehensive than basic REST API wrappers because it exposes comment management and search alongside CRUD operations; more flexible than Linear's UI because it allows programmatic bulk operations and custom filtering.
project and initiative hierarchy navigation
Provides 5 project tools (get_project, list_projects, create_project, update_project, delete_project) and 10 initiative tools (get_initiative, list_initiatives, create_initiative, update_initiative, delete_initiative, link_initiative_to_project, etc.) that enable navigation and management of Linear's organizational hierarchy. Projects group issues; initiatives group projects. Handlers support filtering by team, status, and custom fields. The link_initiative_to_project tool enables cross-linking between organizational levels.
Unique: Separates project and initiative tools into distinct handlers, allowing AI agents to reason about organizational structure at different levels. The link_initiative_to_project tool enables cross-level operations without requiring the agent to manage IDs manually.
vs alternatives: More useful than flat issue lists because it exposes hierarchical structure, enabling agents to understand context before creating issues; more flexible than Linear's UI because it allows programmatic navigation and linking.
cycle and sprint management
Exposes 3 cycle tools (get_cycle, list_cycles, create_cycle) that manage Linear's sprint/cycle abstraction. Cycles group issues into time-boxed iterations with start/end dates and status (planned, active, completed). Handlers support filtering by team and status. The create_cycle tool enables programmatic sprint planning. Cycles are the primary unit for iteration planning in Linear.
Unique: Exposes cycles as a first-class entity separate from issues, enabling agents to reason about sprint structure independently. The create_cycle tool uses ISO date strings for start/end times, enabling precise sprint planning without timezone confusion.
vs alternatives: More useful than issue-level cycle assignment because it enables agents to understand sprint structure upfront; simpler than custom sprint management tools because it leverages Linear's native cycle abstraction.
team and workflow configuration access
Provides 2 team/workflow tools (get_team, list_teams) that expose team metadata, workflow states, and status definitions. Handlers return team names, descriptions, members, and available workflow states (e.g., Backlog, Todo, In Progress, Done). This enables AI agents to understand team structure and valid issue states before creating or updating issues.
Unique: Exposes workflow states as part of team metadata, enabling agents to discover valid status values dynamically rather than hard-coding them. This makes the agent adaptable to custom Linear workflows.
vs alternatives: More flexible than hard-coded status lists because it discovers workflow states from the Linear API; more useful than team-only tools because it includes workflow configuration.
user and organization identity resolution
Provides 4 user/organization tools (get_user, list_users, get_organization, get_viewer) that resolve user identities and organization metadata. The get_viewer tool returns the authenticated user's identity (useful for determining who is running the agent). Handlers support filtering users by team or status. This enables agents to map user names to IDs and understand organization context.
Unique: The get_viewer tool provides a way for agents to determine their own identity without requiring the user to pass it explicitly. This is useful for audit trails and permission checks.
vs alternatives: More useful than static user lists because it discovers users dynamically from the Linear API; more secure than embedding user IDs because it resolves names at runtime.
stateless, token-based authentication with multiple deployment modes
Authenticates to Linear using Personal API Tokens supplied via environment variable (LINEAR_API_TOKEN) or CLI flag (--token), parsed by yargs in src/index.ts. The token is passed to @linear/sdk's LinearClient constructor and never stored by the server. Supports three deployment modes: npx (recommended), Docker, and Smithery. The runServer() function in src/index.ts bootstraps authentication before initializing the MCP server. No session management or token refresh logic is required because Linear tokens do not expire.
Unique: Supports three deployment modes (npx, Docker, Smithery) with consistent authentication logic, eliminating the need for environment-specific configuration. The token is resolved early in runServer() and never stored, reducing the attack surface.
vs alternatives: More flexible than hardcoded tokens because it supports environment variables and CLI flags; more secure than session-based auth because tokens are stateless and never persisted; more portable than custom deployment scripts because it supports standard deployment platforms.
+1 more capabilities