linear-toon-mcp 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc4a8872f9db60b36c89019d376e06b28c95ea1d881c62996c0cf05e65e8ccb5
-  data.tar.gz: 479e37c017575c68fda311020066518211956fe2416d76c16e337114d20d9cc0
+  metadata.gz: b7241fefeb39d4de3f8649fa66bede65615fa0eda60aa1206f121f3c2e30d0d8
+  data.tar.gz: d0eefcd97e9ff4fd27ca48efde69eeb6124a082b81f619671c5a67c8d3cc817e
 SHA512:
-  metadata.gz: e4967b288c7ee386c448b03acecc0c74b9d7134c88efa23179341a7ab6433e6e58372a84df06a0a835c60bde9522d699a0f57572e56365541521a1161f8e52e5
-  data.tar.gz: '078f01ebb0c2b14ba592e065b3bc131768e1ec1d51df887cbae0abd4dcb8b32f48c89e15d54b027d889d6b88ba524c95f8a9ff40685853d1b9244d496f122ffa'
+  metadata.gz: 3275b9582f4ea6d2a800e2dbc08f64e81e82932a5ec9a545ccdc7dea5d3935fd65a18aec825c464e17cbd724dfc04f239f9cb187a5c70cb2df25299576cdbb9d
+  data.tar.gz: b65c95f035164b0ea5eddc6f703716779040828e20d42b889992244de18bb95053178933af1a7a5f9406a4c567d8a6fed80ed8966a04641a8700ff9dec122b8f

data/README.md

@@ -37,7 +37,7 @@ Get your API key from [Linear Settings > API](https://linear.app/settings/api).
 ### Claude Code
 
 ```bash
-claude mcp add -e LINEAR_API_KEY=lin_api_xxxxx linear-toon -- linear-toon-mcp
+claude mcp add linear-toon -e LINEAR_API_KEY=lin_api_xxxxx -- linear-toon-mcp
 ```
 
 ## Tools
@@ -52,6 +52,7 @@ claude mcp add -e LINEAR_API_KEY=lin_api_xxxxx linear-toon -- linear-toon-mcp
 | `list_issue_labels` | List issue labels, optionally scoped to a team. Returns label id and name. |
 | `list_projects` | List projects, optionally scoped to a team. Returns project id, name, and state. |
 | `list_cycles` | List cycles for a team. Returns cycle id, name, number, startsAt, and endsAt. Requires team name or UUID. |
+| `get_project` | Retrieve a specific project by name, ID, or slug. Returns project details including state, priority, dates, progress, and lead. Optional includes for members, milestones, and resources. |
 | `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. |

data/lib/linear_toon_mcp/resolvers.rb

@@ -110,12 +110,18 @@ module LinearToonMcp
     end
 
     # @param client [Client]
-    # @param value [String] project UUID or name
+    # @param value [String] project UUID, name, or slug
     # @return [String] project UUID
     # @raise [Error] when project not found
     def resolve_project(client, value)
       return value if value.match?(UUID_RE)
+
+      # Try name first, then slug
       data = client.query(PROJECT_QUERY, variables: {filter: {name: {eqIgnoreCase: value}}})
+      id = data.dig("projects", "nodes", 0, "id")
+      return id if id
+
+      data = client.query(PROJECT_QUERY, variables: {filter: {slugId: {eqIgnoreCase: value}}})
       data.dig("projects", "nodes", 0, "id") or raise Error, "Project not found: #{value}"
     end
 

data/lib/linear_toon_mcp/tools/get_project.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "toon"
+
+module LinearToonMcp
+  module Tools
+    # Fetch a single Linear project by ID, name, or slug and return it as TOON.
+    # Supports optional includes for members, milestones, and resources.
+    class GetProject < MCP::Tool
+      description "Retrieve details of a specific project in Linear"
+
+      annotations(
+        read_only_hint: true,
+        destructive_hint: false,
+        idempotent_hint: true
+      )
+
+      input_schema(
+        properties: {
+          query: {type: "string", description: "Project name, ID, or slug"},
+          includeMembers: {type: "boolean", description: "Include project members (default: false)"},
+          includeMilestones: {type: "boolean", description: "Include milestones (default: false)"},
+          includeResources: {type: "boolean", description: "Include resources (documents) (default: false)"}
+        },
+        required: ["query"],
+        additionalProperties: false
+      )
+
+      BASE_FIELDS = <<~GRAPHQL
+        id
+        name
+        slugId
+        icon
+        color
+        url
+        description
+        state
+        priority
+        priorityLabel
+        startDate
+        targetDate
+        createdAt
+        updatedAt
+        archivedAt
+        progress
+        scope
+        completedScopeHistory
+        lead { id name }
+        status { id name }
+        teams { nodes { id name } }
+        labels { nodes { id name } }
+        initiatives { nodes { id name } }
+      GRAPHQL
+
+      MEMBERS_FIELDS = "members { nodes { id name email } }"
+      MILESTONES_FIELDS = "projectMilestones { nodes { id name targetDate } }"
+      RESOURCES_FIELDS = "documents { nodes { id title } }"
+
+      # standard:disable Naming/VariableName
+      class << self
+        # @param query [String] Project ID, name, or slug
+        # @param includeMembers [Boolean] Include project members
+        # @param includeMilestones [Boolean] Include project milestones
+        # @param includeResources [Boolean] Include documents
+        # @param server_context [Hash, nil] must contain +:client+ key with a {Client}
+        # @return [MCP::Tool::Response] TOON-encoded project or error
+        def call(query:, includeMembers: false, includeMilestones: false, includeResources: false, server_context: nil)
+          client = server_context&.dig(:client) or raise Error, "client missing from server_context"
+          project_id = Resolvers.resolve_project(client, query)
+          graphql = build_query(includeMembers:, includeMilestones:, includeResources:)
+          data = client.query(graphql, variables: {id: project_id})
+          project = data["project"] or raise Error, "Project not found: #{query}"
+          text = Toon.encode(project)
+          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_query(includeMembers:, includeMilestones:, includeResources:)
+          fields = [BASE_FIELDS.strip]
+          fields << MEMBERS_FIELDS if includeMembers
+          fields << MILESTONES_FIELDS if includeMilestones
+          fields << RESOURCES_FIELDS if includeResources
+
+          <<~GRAPHQL
+            query($id: String!) {
+              project(id: $id) {
+                #{fields.join("\n        ")}
+              }
+            }
+          GRAPHQL
+        end
+      end
+      # standard:enable Naming/VariableName
+    end
+  end
+end

data/lib/linear_toon_mcp/version.rb

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

data/lib/linear_toon_mcp.rb

@@ -15,6 +15,7 @@ require_relative "linear_toon_mcp/tools/list_users"
 require_relative "linear_toon_mcp/tools/list_issue_labels"
 require_relative "linear_toon_mcp/tools/list_projects"
 require_relative "linear_toon_mcp/tools/list_cycles"
+require_relative "linear_toon_mcp/tools/get_project"
 
 # Token-efficient MCP server for Linear. Wraps Linear's GraphQL API
 # and returns TOON-formatted responses for ~40-60% token savings.
@@ -30,7 +31,7 @@ module LinearToonMcp
       name: "linear-toon-mcp",
       version: VERSION,
       description: "Manage Linear issues, projects, and teams",
-      tools: [Tools::GetIssue, Tools::ListIssues, Tools::ListIssueStatuses, Tools::ListTeams, Tools::ListUsers, Tools::ListIssueLabels, Tools::ListProjects, Tools::ListCycles, Tools::CreateComment, Tools::CreateIssue, Tools::UpdateIssue],
+      tools: [Tools::GetIssue, Tools::ListIssues, Tools::ListIssueStatuses, Tools::ListTeams, Tools::ListUsers, Tools::ListIssueLabels, Tools::ListProjects, Tools::ListCycles, Tools::GetProject, Tools::CreateComment, Tools::CreateIssue, Tools::UpdateIssue],
       server_context: {client:}
     )
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: linear-toon-mcp
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Yevhenii Hurin
@@ -69,6 +69,7 @@ files:
 - 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/get_project.rb
 - lib/linear_toon_mcp/tools/list_cycles.rb
 - lib/linear_toon_mcp/tools/list_issue_labels.rb
 - lib/linear_toon_mcp/tools/list_issue_statuses.rb