linear-toon-mcp 0.0.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3832b203213cea96ab6f1a9bf4cb84599cda2d787ade784c7f823e121278c6a9
-  data.tar.gz: a9b7f72796a1511eb15c828c1e4725af6926b3a40b568beca402512b97f21e58
+  metadata.gz: 6b25cc1890ddb1f779b8adcd4636e6d4415035c671e91f5da91f5df78d5b03e6
+  data.tar.gz: ee755802e2a8ab10e7008c0a21779fe1a4058a29ca117d2c56cb9d8761620854
 SHA512:
-  metadata.gz: b3d8fd5d7acaf9abda70b2c612a425eca4af435331a2088669f89564f28fb4166e74eecbbc54607a027b0e97dbdc0ee7abdfe026a22839a98030654b4fe0ac16
-  data.tar.gz: f218f5f454747918fc0a522cc91622f2c899edc52af3f097da95fcbabf0aeac5a9c4e8e49c2afd0cc8686a3a2d1c943fb2a055939392b14e2e7575f8b920137b
+  metadata.gz: cef723735b39f80756443f1a680816633f9a7c1605d68f7a4c4fd177d37c754e3ec5a9328e5c868c726f1d47429ea9ee6f7221aab4a74f917ecb271b67717270
+  data.tar.gz: 2032d28b1e54dc569a8dccd96e06544056d1c06168e4170d2c1f3e7f1b6c5e7c08a1b4881ca0a546349a97329175f2516e883bcecdf52555b55a1447538cfe60

data/README.md

@@ -36,21 +36,20 @@ Get your API key from [Linear Settings > API](https://linear.app/settings/api).
 
 ### Claude Code
 
-Add to your MCP config (`.mcp.json` or Claude Code settings):
-
-```json
-{
-  "mcpServers": {
-    "linear": {
-      "command": "linear-toon-mcp",
-      "env": {
-        "LINEAR_API_KEY": "lin_api_xxxxx"
-      }
-    }
-  }
-}
+```bash
+claude mcp add -e LINEAR_API_KEY=lin_api_xxxxx linear-toon -- linear-toon-mcp
 ```
 
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_issue` | Retrieve a Linear issue by ID or identifier (e.g., `LIN-123`). Returns issue details including title, description, state, assignee, labels, project, and attachments. |
+| `list_issues` | List issues with optional filters (team, assignee, state, label, priority, project, cycle) and cursor-based pagination. Supports name or UUID for most filters. |
+| `create_issue` | Create a new Linear issue. Accepts human-friendly names for team, assignee, state, labels, project, cycle, and milestone (resolved to IDs automatically). Supports issue relations and link attachments. |
+| `update_issue` | Update an existing Linear issue by ID. Supports partial updates, null to remove fields, and relation replacement. |
+| `create_comment` | Create a comment on a Linear issue. Supports Markdown content and threaded replies via parentId. |
+
 ## Development
 
 ```bash

data/lib/linear_toon_mcp/client.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module LinearToonMcp
+  # Minimal HTTP client for Linear's GraphQL API.
+  class Client
+    ENDPOINT = URI("https://api.linear.app/graphql").freeze
+
+    # @param api_key [String] Linear API key (defaults to +LINEAR_API_KEY+ env var)
+    # @raise [ArgumentError] when API key is nil or empty
+    def initialize(api_key: ENV["LINEAR_API_KEY"])
+      raise ArgumentError, "LINEAR_API_KEY is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+    end
+
+    # Execute a GraphQL query against Linear API.
+    # @param query_string [String] GraphQL query
+    # @param variables [Hash] query variables
+    # @return [Hash] the +data+ key from the GraphQL response
+    # @raise [Error] on HTTP errors, GraphQL errors, or empty responses
+    def query(query_string, variables: {})
+      response = post(query_string, variables)
+
+      body = begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        messages = body&.dig("errors")&.map { |e| e["message"] }&.join("; ")
+        raise Error, "HTTP #{response.code}: #{messages || response.body}"
+      end
+
+      raise Error, "Empty response from Linear API" unless body
+
+      if body["errors"]&.any?
+        messages = body["errors"].map { |e| e["message"] }.join("; ")
+        raise Error, "GraphQL error: #{messages}"
+      end
+
+      body["data"]
+    end
+
+    private
+
+    def post(query_string, variables)
+      request = Net::HTTP::Post.new(ENDPOINT)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = @api_key
+      request.body = JSON.generate(query: query_string, variables:)
+
+      Net::HTTP.start(ENDPOINT.host, ENDPOINT.port, use_ssl: true) do |http|
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/linear_toon_mcp/resolvers.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module LinearToonMcp
+  # Shared resolvers for converting human-friendly names to Linear API UUIDs.
+  # Each resolver passes through UUIDs unchanged and performs a GraphQL lookup otherwise.
+  module Resolvers
+    UUID_RE = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+    NUMERIC_RE = /\A\d+\z/
+
+    TEAM_QUERY = <<~GRAPHQL
+      query($filter: TeamFilter) {
+        teams(filter: $filter, first: 1) { nodes { id } }
+      }
+    GRAPHQL
+
+    VIEWER_QUERY = "query { viewer { id } }"
+
+    USER_QUERY = <<~GRAPHQL
+      query($filter: UserFilter) {
+        users(filter: $filter, first: 1) { nodes { id } }
+      }
+    GRAPHQL
+
+    STATE_QUERY = <<~GRAPHQL
+      query($filter: WorkflowStateFilter) {
+        workflowStates(filter: $filter, first: 1) { nodes { id } }
+      }
+    GRAPHQL
+
+    LABEL_QUERY = <<~GRAPHQL
+      query($filter: IssueLabelFilter) {
+        issueLabels(filter: $filter, first: 1) { nodes { id } }
+      }
+    GRAPHQL
+
+    PROJECT_QUERY = <<~GRAPHQL
+      query($filter: ProjectFilter) {
+        projects(filter: $filter, first: 1) { nodes { id } }
+      }
+    GRAPHQL
+
+    CYCLE_QUERY = <<~GRAPHQL
+      query($filter: CycleFilter) {
+        cycles(filter: $filter, first: 1) { nodes { id } }
+      }
+    GRAPHQL
+
+    MILESTONE_QUERY = <<~GRAPHQL
+      query($filter: ProjectMilestoneFilter) {
+        projectMilestones(filter: $filter, first: 1) { nodes { id } }
+      }
+    GRAPHQL
+
+    module_function
+
+    # @param client [Client]
+    # @param value [String] team UUID or name
+    # @return [String] team UUID
+    # @raise [Error] when team not found
+    def resolve_team(client, value)
+      return value if value.match?(UUID_RE)
+      data = client.query(TEAM_QUERY, variables: {filter: {name: {eqIgnoreCase: value}}})
+      data.dig("teams", "nodes", 0, "id") or raise Error, "Team not found: #{value}"
+    end
+
+    # @param client [Client]
+    # @param value [String] user UUID, "me", email, or name
+    # @return [String] user UUID
+    # @raise [Error] when user not found
+    def resolve_user(client, value)
+      return value if value.match?(UUID_RE)
+
+      if value == "me"
+        data = client.query(VIEWER_QUERY)
+        return data.dig("viewer", "id") || raise(Error, "Could not resolve current user")
+      end
+
+      filter = value.include?("@") ? {email: {eq: value}} : {name: {eqIgnoreCase: value}}
+      data = client.query(USER_QUERY, variables: {filter:})
+      data.dig("users", "nodes", 0, "id") or raise Error, "User not found: #{value}"
+    end
+
+    # @param client [Client]
+    # @param team_id [String] team UUID (for scoping)
+    # @param value [String] state UUID or name
+    # @return [String] state UUID
+    # @raise [Error] when state not found
+    def resolve_state(client, team_id, value)
+      return value if value.match?(UUID_RE)
+      filter = {name: {eqIgnoreCase: value}, team: {id: {eq: team_id}}}
+      data = client.query(STATE_QUERY, variables: {filter:})
+      data.dig("workflowStates", "nodes", 0, "id") or raise Error, "State not found: #{value}"
+    end
+
+    # @param client [Client]
+    # @param value [String] label UUID or name
+    # @return [String] label UUID
+    # @raise [Error] when label not found
+    def resolve_label(client, value)
+      return value if value.match?(UUID_RE)
+      data = client.query(LABEL_QUERY, variables: {filter: {name: {eqIgnoreCase: value}}})
+      data.dig("issueLabels", "nodes", 0, "id") or raise Error, "Label not found: #{value}"
+    end
+
+    # @param client [Client]
+    # @param values [Array<String>] label UUIDs or names
+    # @return [Array<String>] label UUIDs
+    def resolve_labels(client, values)
+      values.map { |v| resolve_label(client, v) }
+    end
+
+    # @param client [Client]
+    # @param value [String] project UUID or name
+    # @return [String] project UUID
+    # @raise [Error] when project not found
+    def resolve_project(client, value)
+      return value if value.match?(UUID_RE)
+      data = client.query(PROJECT_QUERY, variables: {filter: {name: {eqIgnoreCase: value}}})
+      data.dig("projects", "nodes", 0, "id") or raise Error, "Project not found: #{value}"
+    end
+
+    # @param client [Client]
+    # @param team_id [String] team UUID (for scoping)
+    # @param value [String] cycle UUID, number, or name
+    # @return [String] cycle UUID
+    # @raise [Error] when cycle not found
+    def resolve_cycle(client, team_id, value)
+      return value if value.match?(UUID_RE)
+
+      filter = if value.match?(NUMERIC_RE)
+        {number: {eq: value.to_i}, team: {id: {eq: team_id}}}
+      else
+        {name: {eqIgnoreCase: value}, team: {id: {eq: team_id}}}
+      end
+
+      data = client.query(CYCLE_QUERY, variables: {filter:})
+      data.dig("cycles", "nodes", 0, "id") or raise Error, "Cycle not found: #{value}"
+    end
+
+    # @param client [Client]
+    # @param project_id [String] project UUID (for scoping)
+    # @param value [String] milestone UUID or name
+    # @return [String] milestone UUID
+    # @raise [Error] when milestone not found
+    def resolve_milestone(client, project_id, value)
+      return value if value.match?(UUID_RE)
+      filter = {name: {eqIgnoreCase: value}, project: {id: {eq: project_id}}}
+      data = client.query(MILESTONE_QUERY, variables: {filter:})
+      data.dig("projectMilestones", "nodes", 0, "id") or raise Error, "Milestone not found: #{value}"
+    end
+  end
+end

data/lib/linear_toon_mcp/tools/create_comment.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "toon"
+
+module LinearToonMcp
+  module Tools
+    # Create a comment on a Linear issue. Supports Markdown content
+    # and threaded replies via parentId.
+    class CreateComment < MCP::Tool
+      description "Create a comment on a Linear issue"
+
+      annotations(
+        read_only_hint: false,
+        destructive_hint: false,
+        idempotent_hint: false
+      )
+
+      input_schema(
+        properties: {
+          issueId: {type: "string", description: "Issue ID"},
+          body: {type: "string", description: "Content as Markdown"},
+          parentId: {type: "string", description: "Parent comment ID (for replies)"}
+        },
+        required: ["issueId", "body"],
+        additionalProperties: false
+      )
+
+      MUTATION = <<~GRAPHQL
+        mutation($input: CommentCreateInput!) {
+          commentCreate(input: $input) {
+            success
+            comment {
+              id
+              body
+              createdAt
+              user { id name }
+              issue { id identifier }
+            }
+          }
+        }
+      GRAPHQL
+
+      # standard:disable Naming/VariableName
+      class << self
+        # @param issueId [String] Linear issue ID
+        # @param body [String] comment content as Markdown
+        # @param parentId [String, nil] parent comment ID for threaded replies
+        # @param server_context [Hash, nil] must contain +:client+ key with a {Client}
+        # @return [MCP::Tool::Response] TOON-encoded comment or error
+        def call(issueId:, body:, parentId: nil, server_context: nil)
+          client = server_context&.dig(:client) or raise Error, "client missing from server_context"
+
+          input = {issueId:, body:}
+          input[:parentId] = parentId if parentId
+
+          data = client.query(MUTATION, variables: {input:})
+          result = data["commentCreate"]
+          raise Error, "Comment creation failed" unless result["success"]
+
+          text = Toon.encode(result["comment"])
+          MCP::Tool::Response.new([{type: "text", text:}])
+        rescue Error => e
+          MCP::Tool::Response.new([{type: "text", text: e.message}], error: true)
+        end
+      end
+      # standard:enable Naming/VariableName
+    end
+  end
+end

data/lib/linear_toon_mcp/tools/create_issue.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "toon"
+
+module LinearToonMcp
+  module Tools
+    # Create a new Linear issue with full parameter support.
+    # Resolves human-friendly names to IDs for team, assignee, state, labels,
+    # project, cycle, and milestone. Supports post-mutation relations and links.
+    class CreateIssue < MCP::Tool
+      description "Create a new Linear issue"
+
+      annotations(
+        read_only_hint: false,
+        destructive_hint: false,
+        idempotent_hint: false
+      )
+
+      # standard:disable Layout/LineLength
+      input_schema(
+        properties: {
+          title: {type: "string", description: "Issue title"},
+          team: {type: "string", description: "Team name or ID"},
+          description: {type: "string", description: "Content as Markdown"},
+          assignee: {type: "string", description: 'User ID, name, email, or "me"'},
+          priority: {type: "number", description: "0=None, 1=Urgent, 2=High, 3=Normal, 4=Low"},
+          state: {type: "string", description: "State name or ID"},
+          labels: {type: "array", items: {type: "string"}, description: "Label names or IDs"},
+          project: {type: "string", description: "Project name or ID"},
+          cycle: {type: "string", description: "Cycle name, number, or ID"},
+          estimate: {type: "number", description: "Issue estimate value"},
+          dueDate: {type: "string", description: "Due date (ISO format)"},
+          parentId: {type: "string", description: "Parent issue ID"},
+          blockedBy: {type: "array", items: {type: "string"}, description: "Issue IDs/identifiers blocking this"},
+          blocks: {type: "array", items: {type: "string"}, description: "Issue IDs/identifiers this blocks"},
+          relatedTo: {type: "array", items: {type: "string"}, description: "Related issue IDs/identifiers"},
+          duplicateOf: {type: "string", description: "Duplicate of issue ID/identifier"},
+          milestone: {type: "string", description: "Milestone name or ID"},
+          delegate: {type: "string", description: "Agent name or ID"},
+          links: {type: "array", items: {type: "object", properties: {url: {type: "string"}, title: {type: "string"}}, required: ["url", "title"]}, description: "Link attachments [{url, title}]"}
+        },
+        required: ["title", "team"],
+        additionalProperties: false
+      )
+      # standard:enable Layout/LineLength
+
+      MUTATION = <<~GRAPHQL
+        mutation($input: IssueCreateInput!) {
+          issueCreate(input: $input) {
+            success
+            issue {
+              id identifier title url
+              state { name }
+              assignee { id name }
+              team { id name }
+              labels { nodes { name } }
+              project { id name }
+            }
+          }
+        }
+      GRAPHQL
+
+      RELATION_MUTATION = <<~GRAPHQL
+        mutation($input: IssueRelationCreateInput!) {
+          issueRelationCreate(input: $input) { success }
+        }
+      GRAPHQL
+
+      LINK_MUTATION = <<~GRAPHQL
+        mutation($url: String!, $issueId: String!, $title: String) {
+          attachmentLinkURL(url: $url, issueId: $issueId, title: $title) { success }
+        }
+      GRAPHQL
+
+      # standard:disable Naming/VariableName, Metrics/MethodLength
+      class << self
+        # @param title [String] issue title
+        # @param team [String] team name or UUID
+        # @param server_context [Hash, nil] must contain +:client+ key
+        # @return [MCP::Tool::Response] TOON-encoded issue or error
+        def call(title:, team:, server_context: nil, **kwargs)
+          client = server_context&.dig(:client) or raise Error, "client missing from server_context"
+          raise Error, "Cannot specify both assignee and delegate" if kwargs.key?(:assignee) && kwargs.key?(:delegate)
+
+          team_id = Resolvers.resolve_team(client, team)
+          input = {title:, teamId: team_id}
+
+          add_direct_fields(input, **kwargs)
+          resolve_fields(input, client, team_id, **kwargs)
+
+          data = client.query(MUTATION, variables: {input:})
+          result = data["issueCreate"]
+          raise Error, "Issue creation failed" unless result["success"]
+
+          issue = result["issue"]
+          create_relations(client, issue["id"], **kwargs)
+          create_links(client, issue["id"], kwargs[:links])
+
+          text = Toon.encode(issue)
+          MCP::Tool::Response.new([{type: "text", text:}])
+        rescue Error => e
+          MCP::Tool::Response.new([{type: "text", text: e.message}], error: true)
+        end
+
+        private
+
+        def add_direct_fields(input, description: nil, priority: nil, estimate: nil,
+          dueDate: nil, parentId: nil, **)
+          input[:description] = description if description
+          input[:priority] = priority if priority
+          input[:estimate] = estimate if estimate
+          input[:dueDate] = dueDate if dueDate
+          input[:parentId] = parentId if parentId
+        end
+
+        def resolve_fields(input, client, team_id, assignee: nil, state: nil, labels: nil,
+          project: nil, cycle: nil, milestone: nil, delegate: nil, **)
+          input[:assigneeId] = Resolvers.resolve_user(client, delegate || assignee) if assignee || delegate
+          input[:stateId] = Resolvers.resolve_state(client, team_id, state) if state
+          input[:labelIds] = Resolvers.resolve_labels(client, labels) if labels
+          project_id = Resolvers.resolve_project(client, project) if project
+          input[:projectId] = project_id if project_id
+          input[:cycleId] = Resolvers.resolve_cycle(client, team_id, cycle) if cycle
+          if milestone
+            raise Error, "milestone requires project" unless project_id
+            input[:projectMilestoneId] = Resolvers.resolve_milestone(client, project_id, milestone)
+          end
+        end
+
+        def create_relations(client, issue_id, blockedBy: nil, blocks: nil, relatedTo: nil, duplicateOf: nil, **)
+          Array(blockedBy).each { |id| create_relation(client, issue_id, id, "isBlockedBy") }
+          Array(blocks).each { |id| create_relation(client, issue_id, id, "blocks") }
+          Array(relatedTo).each { |id| create_relation(client, issue_id, id, "related") }
+          create_relation(client, issue_id, duplicateOf, "duplicate") if duplicateOf
+        end
+
+        def create_relation(client, issue_id, related_issue_id, type)
+          input = {issueId: issue_id, relatedIssueId: related_issue_id, type:}
+          data = client.query(RELATION_MUTATION, variables: {input:})
+          return if data.dig("issueRelationCreate", "success")
+          raise Error, "Failed to create #{type} relation with #{related_issue_id}"
+        end
+
+        def create_links(client, issue_id, links)
+          return unless links
+
+          links.each do |link|
+            data = client.query(LINK_MUTATION, variables: {url: link["url"], issueId: issue_id, title: link["title"]})
+            next if data.dig("attachmentLinkURL", "success")
+            raise Error, "Failed to attach link: #{link["url"]}"
+          end
+        end
+      end
+      # standard:enable Naming/VariableName, Metrics/MethodLength
+    end
+  end
+end

data/lib/linear_toon_mcp/tools/get_issue.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "toon"
+
+module LinearToonMcp
+  module Tools
+    # Fetch a single Linear issue by ID or identifier and return it as TOON.
+    # Includes metadata, state, assignee, labels, project, team, and attachments.
+    class GetIssue < MCP::Tool
+      description "Retrieve a Linear issue by ID"
+
+      annotations(
+        read_only_hint: true,
+        destructive_hint: false,
+        idempotent_hint: true
+      )
+
+      input_schema(
+        properties: {
+          id: {type: "string", description: "Issue ID or identifier (e.g., LIN-123)"}
+        },
+        required: ["id"],
+        additionalProperties: false
+      )
+
+      QUERY = <<~GRAPHQL
+        query($id: String!) {
+          issue(id: $id) {
+            id
+            identifier
+            title
+            description
+            priority
+            priorityLabel
+            url
+            branchName
+            createdAt
+            updatedAt
+            archivedAt
+            completedAt
+            dueDate
+            state { name }
+            assignee { id name }
+            creator { id name }
+            labels { nodes { name } }
+            project { id name }
+            team { id name }
+            attachments { nodes { id title url } }
+          }
+        }
+      GRAPHQL
+
+      class << self
+        # @param id [String] Linear issue ID or identifier (e.g., "LIN-123")
+        # @param server_context [Hash, nil] must contain +:client+ key with a {Client}
+        # @return [MCP::Tool::Response] TOON-encoded issue or error
+        def call(id:, server_context: nil)
+          client = server_context&.dig(:client) or raise Error, "client missing from server_context"
+          data = client.query(QUERY, variables: {id:})
+          issue = data["issue"] or raise Error, "Issue not found: #{id}"
+          text = Toon.encode(issue)
+          MCP::Tool::Response.new([{type: "text", text:}])
+        rescue Error => e
+          MCP::Tool::Response.new([{type: "text", text: e.message}], error: true)
+        end
+      end
+    end
+  end
+end

data/lib/linear_toon_mcp/tools/list_issues.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "toon"
+
+module LinearToonMcp
+  module Tools
+    # List Linear issues with optional filters and pagination.
+    # Returns TOON-encoded array with page info for cursor-based pagination.
+    class ListIssues < MCP::Tool
+      description "List issues with optional filters and pagination"
+
+      annotations(
+        read_only_hint: true,
+        destructive_hint: false,
+        idempotent_hint: true
+      )
+
+      input_schema(
+        properties: {
+          assignee: {type: "string", description: 'User ID, name, email, or "me"'},
+          createdAt: {type: "string", description: "Created after: ISO-8601 date/duration (e.g., -P1D)"},
+          cursor: {type: "string", description: "Next page cursor"},
+          cycle: {type: "string", description: "Cycle name, number, or ID"},
+          delegate: {type: "string", description: "Agent name or ID"},
+          includeArchived: {type: "boolean", description: "Include archived items (default true)"},
+          label: {type: "string", description: "Label name or ID"},
+          limit: {type: "integer", description: "Max results (default 50, max 250)"},
+          orderBy: {type: "string", description: "createdAt or updatedAt (default updatedAt)", enum: ["createdAt", "updatedAt"]},
+          parentId: {type: "string", description: "Parent issue ID"},
+          priority: {type: "integer", description: "0=None, 1=Urgent, 2=High, 3=Normal, 4=Low"},
+          project: {type: "string", description: "Project name or ID"},
+          query: {type: "string", description: "Search issue title or description"},
+          state: {type: "string", description: "State name or ID"},
+          team: {type: "string", description: "Team name or ID"},
+          updatedAt: {type: "string", description: "Updated after: ISO-8601 date/duration (e.g., -P1D)"}
+        },
+        additionalProperties: false
+      )
+
+      QUERY = <<~GRAPHQL
+        query($filter: IssueFilter, $first: Int, $after: String, $orderBy: PaginationOrderBy, $includeArchived: Boolean) {
+          issues(filter: $filter, first: $first, after: $after, orderBy: $orderBy, includeArchived: $includeArchived) {
+            nodes {
+              id
+              identifier
+              title
+              priority
+              priorityLabel
+              url
+              createdAt
+              updatedAt
+              state { name }
+              assignee { id name }
+              labels { nodes { name } }
+              project { id name }
+              team { id name }
+            }
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+          }
+        }
+      GRAPHQL
+
+      UUID_RE = Resolvers::UUID_RE
+      NUMERIC_RE = Resolvers::NUMERIC_RE
+
+      # standard:disable Naming/VariableName
+      class << self
+        # @param assignee [String, nil] user ID, name, email, or "me"
+        # @param createdAt [String, nil] ISO-8601 date or duration
+        # @param cursor [String, nil] pagination cursor
+        # @param cycle [String, nil] cycle name, number, or ID
+        # @param delegate [String, nil] agent name or ID
+        # @param includeArchived [Boolean, nil] include archived issues
+        # @param label [String, nil] label name or ID
+        # @param limit [Integer, nil] max results (default 50, max 250)
+        # @param orderBy [String, nil] "createdAt" or "updatedAt"
+        # @param parentId [String, nil] parent issue ID
+        # @param priority [Integer, nil] 0-4
+        # @param project [String, nil] project name or ID
+        # @param query [String, nil] search title or description
+        # @param state [String, nil] state name or ID
+        # @param team [String, nil] team name or ID
+        # @param updatedAt [String, nil] ISO-8601 date or duration
+        # @param server_context [Hash, nil] must contain +:client+ key with a {Client}
+        # @return [MCP::Tool::Response] TOON-encoded issue list or error
+        def call(assignee: nil, createdAt: nil, cursor: nil, cycle: nil,
+          delegate: nil, includeArchived: nil, label: nil, limit: nil, orderBy: nil,
+          parentId: nil, priority: nil, project: nil, query: nil, state: nil,
+          team: nil, updatedAt: nil, server_context: nil)
+          client = server_context&.dig(:client) or raise Error, "client missing from server_context"
+
+          filter = build_filter(
+            assignee:, team:, project:, state:, label:,
+            priority:, parentId:, cycle:, delegate:,
+            query:, createdAt:, updatedAt:
+          )
+
+          variables = {
+            first: (limit || 50).clamp(1, 250),
+            orderBy: orderBy || "updatedAt",
+            includeArchived: includeArchived != false
+          }
+          variables[:filter] = filter unless filter.empty?
+          variables[:after] = cursor if cursor
+
+          data = client.query(QUERY, variables:)
+          issues = data["issues"] or raise Error, "Unexpected response: missing issues field"
+          text = Toon.encode(issues)
+          MCP::Tool::Response.new([{type: "text", text:}])
+        rescue Error => e
+          MCP::Tool::Response.new([{type: "text", text: e.message}], error: true)
+        end
+
+        private
+
+        def build_filter(assignee:, team:, project:, state:, label:,
+          priority:, parentId:, cycle:, delegate:,
+          query:, createdAt:, updatedAt:)
+          filter = {}
+          filter[:assignee] = assignee_filter(assignee) if assignee
+          filter[:team] = name_or_id(team) if team
+          filter[:project] = name_or_id(project) if project
+          filter[:state] = name_or_id(state) if state
+          filter[:labels] = {some: name_or_id(label)} if label
+          filter[:priority] = {eq: priority} if priority
+          filter[:parent] = {id: {eq: parentId}} if parentId
+          filter[:cycle] = cycle_filter(cycle) if cycle
+          filter[:delegate] = name_or_id(delegate) if delegate
+          if query
+            filter[:or] = [
+              {title: {containsIgnoreCase: query}},
+              {description: {containsIgnoreCase: query}}
+            ]
+          end
+          filter[:createdAt] = {gte: resolve_date(createdAt)} if createdAt
+          filter[:updatedAt] = {gte: resolve_date(updatedAt)} if updatedAt
+          filter
+        end
+        # standard:enable Naming/VariableName
+
+        def assignee_filter(value)
+          return {isMe: {eq: true}} if value == "me"
+          return {id: {eq: value}} if value.match?(UUID_RE)
+          return {email: {eq: value}} if value.include?("@")
+          {name: {eqIgnoreCase: value}}
+        end
+
+        def name_or_id(value)
+          value.match?(UUID_RE) ? {id: {eq: value}} : {name: {eqIgnoreCase: value}}
+        end
+
+        def cycle_filter(value)
+          return {id: {eq: value}} if value.match?(UUID_RE)
+          return {number: {eq: value.to_i}} if value.match?(NUMERIC_RE)
+          {name: {eqIgnoreCase: value}}
+        end
+
+        def resolve_date(value)
+          return value unless value.start_with?("-P")
+          match = value.match(/\A-P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?\z/)
+          raise Error, "Invalid duration: #{value}" unless match
+          days = match.captures.zip([365, 30, 7, 1]).sum { |c, m| (c&.to_i || 0) * m }
+          (Time.now.utc - (days * 86_400)).iso8601
+        end
+      end
+    end
+  end
+end

data/lib/linear_toon_mcp/tools/update_issue.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "toon"
+
+module LinearToonMcp
+  module Tools
+    # Update an existing Linear issue by ID. Supports partial updates,
+    # null to remove fields, and relation replacement semantics.
+    class UpdateIssue < MCP::Tool
+      description "Update an existing Linear issue"
+
+      annotations(
+        read_only_hint: false,
+        destructive_hint: false,
+        idempotent_hint: false
+      )
+
+      # standard:disable Layout/LineLength
+      input_schema(
+        properties: {
+          id: {type: "string", description: "Issue ID"},
+          title: {type: "string", description: "Issue title"},
+          team: {type: "string", description: "Team name or ID"},
+          description: {type: "string", description: "Content as Markdown"},
+          assignee: {type: ["string", "null"], description: 'User ID, name, email, or "me". Null to remove'},
+          priority: {type: "number", description: "0=None, 1=Urgent, 2=High, 3=Normal, 4=Low"},
+          state: {type: "string", description: "State name or ID"},
+          labels: {type: "array", items: {type: "string"}, description: "Label names or IDs"},
+          project: {type: "string", description: "Project name or ID"},
+          cycle: {type: "string", description: "Cycle name, number, or ID"},
+          estimate: {type: "number", description: "Issue estimate value"},
+          dueDate: {type: "string", description: "Due date (ISO format)"},
+          parentId: {type: ["string", "null"], description: "Parent issue ID. Null to remove"},
+          blockedBy: {type: "array", items: {type: "string"}, description: "Issue IDs blocking this. Replaces existing; omit to keep unchanged"},
+          blocks: {type: "array", items: {type: "string"}, description: "Issue IDs this blocks. Replaces existing; omit to keep unchanged"},
+          relatedTo: {type: "array", items: {type: "string"}, description: "Related issue IDs. Replaces existing; omit to keep unchanged"},
+          duplicateOf: {type: ["string", "null"], description: "Duplicate of issue ID. Null to remove"},
+          milestone: {type: "string", description: "Milestone name or ID"},
+          delegate: {type: ["string", "null"], description: "Agent name or ID. Null to remove"},
+          links: {type: "array", items: {type: "object", properties: {url: {type: "string"}, title: {type: "string"}}, required: ["url", "title"]}, description: "Link attachments [{url, title}]"}
+        },
+        required: ["id"],
+        additionalProperties: false
+      )
+      # standard:enable Layout/LineLength
+
+      MUTATION = <<~GRAPHQL
+        mutation($id: String!, $input: IssueUpdateInput!) {
+          issueUpdate(id: $id, input: $input) {
+            success
+            issue {
+              id identifier title url
+              state { name }
+              assignee { id name }
+              team { id name }
+              labels { nodes { name } }
+              project { id name }
+            }
+          }
+        }
+      GRAPHQL
+
+      RELATIONS_QUERY = <<~GRAPHQL
+        query($id: String!) {
+          issue(id: $id) {
+            relations { nodes { id type relatedIssue { id } } }
+          }
+        }
+      GRAPHQL
+
+      RELATION_DELETE_MUTATION = <<~GRAPHQL
+        mutation($id: String!) {
+          issueRelationDelete(id: $id) { success }
+        }
+      GRAPHQL
+
+      ISSUE_TEAM_QUERY = <<~GRAPHQL
+        query($id: String!) {
+          issue(id: $id) { team { id } }
+        }
+      GRAPHQL
+
+      RELATION_MUTATION = <<~GRAPHQL
+        mutation($input: IssueRelationCreateInput!) {
+          issueRelationCreate(input: $input) { success }
+        }
+      GRAPHQL
+
+      LINK_MUTATION = <<~GRAPHQL
+        mutation($url: String!, $issueId: String!, $title: String) {
+          attachmentLinkURL(url: $url, issueId: $issueId, title: $title) { success }
+        }
+      GRAPHQL
+
+      RELATION_TYPE_MAP = {
+        blockedBy: "isBlockedBy",
+        blocks: "blocks",
+        relatedTo: "related",
+        duplicateOf: "duplicate"
+      }.freeze
+
+      # standard:disable Naming/VariableName, Metrics/MethodLength
+      class << self
+        # @param id [String] issue ID
+        # @param server_context [Hash, nil] must contain +:client+ key
+        # @return [MCP::Tool::Response] TOON-encoded issue or error
+        def call(id:, server_context: nil, **kwargs)
+          client = server_context&.dig(:client) or raise Error, "client missing from server_context"
+          raise Error, "Cannot specify both assignee and delegate" if kwargs.key?(:assignee) && kwargs.key?(:delegate)
+
+          input = {}
+          team_id = resolve_team_id(client, id, kwargs)
+          build_input(input, client, team_id, kwargs)
+
+          data = client.query(MUTATION, variables: {id:, input:})
+          result = data["issueUpdate"]
+          raise Error, "Issue update failed" unless result["success"]
+
+          issue = result["issue"]
+          replace_relations(client, id, kwargs)
+          create_links(client, id, kwargs[:links])
+
+          text = Toon.encode(issue)
+          MCP::Tool::Response.new([{type: "text", text:}])
+        rescue Error => e
+          MCP::Tool::Response.new([{type: "text", text: e.message}], error: true)
+        end
+
+        private
+
+        def resolve_team_id(client, issue_id, kwargs)
+          return Resolvers.resolve_team(client, kwargs[:team]) if kwargs.key?(:team)
+          return unless needs_team_id?(kwargs)
+
+          data = client.query(ISSUE_TEAM_QUERY, variables: {id: issue_id})
+          data.dig("issue", "team", "id") or raise Error, "Could not determine issue team"
+        end
+
+        def needs_team_id?(kwargs)
+          kwargs.key?(:state) || kwargs.key?(:cycle)
+        end
+
+        def build_input(input, client, team_id, kwargs)
+          add_direct_fields(input, kwargs)
+          add_nullable_fields(input, client, kwargs)
+          add_resolved_fields(input, client, team_id, kwargs)
+        end
+
+        def add_direct_fields(input, kwargs)
+          {title: :title, description: :description, priority: :priority,
+           estimate: :estimate, dueDate: :dueDate}.each do |key, field|
+            input[field] = kwargs[key] if kwargs.key?(key)
+          end
+        end
+
+        def add_nullable_fields(input, client, kwargs)
+          if kwargs.key?(:assignee)
+            input[:assigneeId] = kwargs[:assignee] ? Resolvers.resolve_user(client, kwargs[:assignee]) : nil
+          end
+          if kwargs.key?(:delegate)
+            input[:assigneeId] = kwargs[:delegate] ? Resolvers.resolve_user(client, kwargs[:delegate]) : nil
+          end
+          input[:parentId] = kwargs[:parentId] if kwargs.key?(:parentId)
+        end
+
+        def add_resolved_fields(input, client, team_id, kwargs)
+          input[:teamId] = team_id if kwargs.key?(:team) && team_id
+          input[:stateId] = Resolvers.resolve_state(client, team_id, kwargs[:state]) if kwargs.key?(:state) && team_id
+          input[:labelIds] = Resolvers.resolve_labels(client, kwargs[:labels]) if kwargs.key?(:labels)
+          project_id = nil
+          if kwargs.key?(:project) && kwargs[:project]
+            project_id = Resolvers.resolve_project(client, kwargs[:project])
+            input[:projectId] = project_id
+          end
+          if kwargs.key?(:milestone)
+            raise Error, "milestone requires project" unless project_id
+            input[:projectMilestoneId] = Resolvers.resolve_milestone(client, project_id, kwargs[:milestone])
+          end
+          input[:cycleId] = Resolvers.resolve_cycle(client, team_id, kwargs[:cycle]) if kwargs.key?(:cycle) && team_id
+        end
+
+        def replace_relations(client, issue_id, kwargs)
+          RELATION_TYPE_MAP.each do |param, type|
+            next unless kwargs.key?(param)
+            values = (param == :duplicateOf) ? [kwargs[param]].compact : Array(kwargs[param])
+            delete_existing_relations(client, issue_id, type)
+            values.each do |related_id|
+              input = {issueId: issue_id, relatedIssueId: related_id, type:}
+              data = client.query(RELATION_MUTATION, variables: {input:})
+              next if data.dig("issueRelationCreate", "success")
+              raise Error, "Failed to create #{type} relation with #{related_id}"
+            end
+          end
+        end
+
+        def delete_existing_relations(client, issue_id, type)
+          data = client.query(RELATIONS_QUERY, variables: {id: issue_id})
+          relations = data.dig("issue", "relations", "nodes") || []
+          relations.each do |rel|
+            next unless rel["type"] == type
+            del = client.query(RELATION_DELETE_MUTATION, variables: {id: rel["id"]})
+            next if del.dig("issueRelationDelete", "success")
+            raise Error, "Failed to delete #{type} relation #{rel["id"]}"
+          end
+        end
+
+        def create_links(client, issue_id, links)
+          return unless links
+
+          links.each do |link|
+            vars = {url: link["url"], issueId: issue_id, title: link["title"]}
+            data = client.query(LINK_MUTATION, variables: vars)
+            next if data.dig("attachmentLinkURL", "success")
+            raise Error, "Failed to attach link: #{link["url"]}"
+          end
+        end
+      end
+      # standard:enable Naming/VariableName, Metrics/MethodLength
+    end
+  end
+end

data/lib/linear_toon_mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LinearToonMcp
-  VERSION = "0.0.1"
+  VERSION = "0.3.0"
 end

data/lib/linear_toon_mcp.rb

@@ -2,17 +2,30 @@
 
 require "mcp"
 require_relative "linear_toon_mcp/version"
-require_relative "linear_toon_mcp/tools/echo"
+require_relative "linear_toon_mcp/client"
+require_relative "linear_toon_mcp/resolvers"
+require_relative "linear_toon_mcp/tools/get_issue"
+require_relative "linear_toon_mcp/tools/list_issues"
+require_relative "linear_toon_mcp/tools/create_comment"
+require_relative "linear_toon_mcp/tools/create_issue"
+require_relative "linear_toon_mcp/tools/update_issue"
 
+# Token-efficient MCP server for Linear. Wraps Linear's GraphQL API
+# and returns TOON-formatted responses for ~40-60% token savings.
 module LinearToonMcp
+  # Raised on Linear API HTTP errors, GraphQL errors, or missing data.
   class Error < StandardError; end
 
-  def self.server
+  # Build a configured MCP::Server with all registered tools.
+  # @param client [Client] Linear API client (defaults to new instance from ENV)
+  # @return [MCP::Server]
+  def self.server(client: Client.new)
     MCP::Server.new(
       name: "linear-toon-mcp",
       version: VERSION,
       description: "Manage Linear issues, projects, and teams",
-      tools: [Tools::Echo]
+      tools: [Tools::GetIssue, Tools::ListIssues, Tools::CreateComment, Tools::CreateIssue, Tools::UpdateIssue],
+      server_context: {client:}
     )
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: linear-toon-mcp
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Yevhenii Hurin
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.1
 - !ruby/object:Gem::Dependency
   name: toon-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -50,7 +64,13 @@ files:
 - README.md
 - bin/linear-toon-mcp
 - lib/linear_toon_mcp.rb
-- lib/linear_toon_mcp/tools/echo.rb
+- lib/linear_toon_mcp/client.rb
+- lib/linear_toon_mcp/resolvers.rb
+- lib/linear_toon_mcp/tools/create_comment.rb
+- lib/linear_toon_mcp/tools/create_issue.rb
+- lib/linear_toon_mcp/tools/get_issue.rb
+- lib/linear_toon_mcp/tools/list_issues.rb
+- lib/linear_toon_mcp/tools/update_issue.rb
 - lib/linear_toon_mcp/version.rb
 homepage: https://github.com/hoblin/linear-toon-mcp
 licenses:

data/lib/linear_toon_mcp/tools/echo.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module LinearToonMcp
-  module Tools
-    class Echo < MCP::Tool
-      description "Accepts text input and returns it as-is"
-
-      annotations(
-        read_only_hint: true,
-        destructive_hint: false,
-        idempotent_hint: true
-      )
-
-      input_schema(
-        properties: {
-          text: {type: "string", description: "Text to echo back"}
-        },
-        required: ["text"],
-        additionalProperties: false
-      )
-
-      class << self
-        def call(text:, server_context: nil)
-          MCP::Tool::Response.new([{type: "text", text:}])
-        end
-      end
-    end
-  end
-end