linear-toon-mcp 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3832b203213cea96ab6f1a9bf4cb84599cda2d787ade784c7f823e121278c6a9
-  data.tar.gz: a9b7f72796a1511eb15c828c1e4725af6926b3a40b568beca402512b97f21e58
+  metadata.gz: 50a8ce17d061de79481c874e5cd0bd06cb2ab7656101798fb9e312ba4e890a4f
+  data.tar.gz: 986cd4e9927a53c969f9a2359013a626b5dfe0b9de2e201b5a5e52cb5faa4635
 SHA512:
-  metadata.gz: b3d8fd5d7acaf9abda70b2c612a425eca4af435331a2088669f89564f28fb4166e74eecbbc54607a027b0e97dbdc0ee7abdfe026a22839a98030654b4fe0ac16
-  data.tar.gz: f218f5f454747918fc0a522cc91622f2c899edc52af3f097da95fcbabf0aeac5a9c4e8e49c2afd0cc8686a3a2d1c943fb2a055939392b14e2e7575f8b920137b
+  metadata.gz: 4755fd71c9c8cf68259264351fd3e9cf9cadf6f1af6371377f28c944ae0af3bf67d300173c382d0eba92a3dd132738a5d7e2e6067dba9721f69ae624ae29d15d
+  data.tar.gz: 0bd32d72d4fe123c043107de21cb50dbe1387b4ae4b76e48ccb4105a7555ffd068991c756acca755666b201a06484ce83c6bd7a03a7134662f06a3a4bddfe17d

data/README.md

@@ -36,21 +36,17 @@ 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. |
+
 ## 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/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,173 @@
+# 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
+
+      # @private
+      UUID_RE = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+      # @private
+      NUMERIC_RE = /\A\d+\z/
+
+      # 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/version.rb

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

data/lib/linear_toon_mcp.rb

@@ -2,17 +2,26 @@
 
 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/tools/get_issue"
+require_relative "linear_toon_mcp/tools/list_issues"
 
+# 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],
+      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.2.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,9 @@ 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/tools/get_issue.rb
+- lib/linear_toon_mcp/tools/list_issues.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