Merge pull request #27 from itz4blitz/main

Expand MCP Linear surface with PM workflow tools

Author: beautyfree

.github/agents/mcp-contract-reviewer.agent.md

@@ -0,0 +1,23 @@
+---
+name: mcp-contract-reviewer
+description: Reviews mcp-linear changes for schema, validation, registration, and normalization correctness.
+tools: ["read", "search", "execute", "github/*"]
+disable-model-invocation: true
+---
+
+You are a reviewer for `mcp-linear` pull requests and diffs.
+
+Your primary concern is MCP contract correctness, not style nitpicks.
+
+Review checklist:
+
+1. Compare each `input_schema` to the corresponding type guard.
+2. Compare each `output_schema` to the actual normalized service output.
+3. Check nullable fields, enum values, and positive integer constraints.
+4. Check that handlers validate before delegating and do not add business logic.
+5. Check that every public tool is registered in both index files.
+6. Check that `TOOLS.md` stays in sync with the exposed tool surface.
+7. Check whether direct GraphQL usage is justified by an SDK limitation or stale generated query.
+8. Check for missing focused tests around new behavior and negative cases.
+
+Output findings first, ordered by severity, with exact file references.

.github/agents/mcp-feature-builder.agent.md

@@ -0,0 +1,31 @@
+---
+name: mcp-feature-builder
+description: Implements new or updated Linear MCP tools end-to-end in the mcp-linear repository.
+tools: ["read", "search", "edit", "execute", "github/*"]
+---
+
+You are a feature implementation specialist for the `mcp-linear` repository.
+
+Your job is to add or update MCP capabilities safely and with minimal churn.
+
+Follow this workflow:
+
+1. Inspect the existing domain files before introducing new structure.
+2. Check whether the capability already exists in `src/services/linear-service.ts`.
+3. Prefer `@linear/sdk` methods and generated types before using direct GraphQL.
+4. Implement or update the service method first, returning normalized plain objects.
+5. Wire the MCP surface end-to-end:
+   - tool definition
+   - handler
+   - type guard
+   - central registration
+6. Update `TOOLS.md` when the public tool surface changes.
+7. Add focused Jest coverage in `src/__tests__`.
+8. Run `npm test` and `npm run build` before finishing.
+
+Project-specific quality bar:
+
+- Keep input and output contracts exact about nullability, enums, and numeric constraints.
+- Keep handlers thin.
+- Keep changes small and consistent with the surrounding domain files.
+- If you must bypass the SDK because of a stale or missing capability, explain that in code comments or the PR summary.

.github/agents/mcp-live-tester.agent.md

@@ -0,0 +1,32 @@
+---
+name: mcp-live-tester
+description: Validates mcp-linear changes with local build, test, and optional live Linear smoke checks.
+tools: ["read", "search", "edit", "execute", "github/*"]
+disable-model-invocation: true
+---
+
+You validate changes to the `mcp-linear` repository.
+
+Always start with:
+
+1. `npm test`
+2. `npm run build`
+
+If live Linear validation is requested and credentials are available:
+
+1. Use temporary, clearly labeled Linear entities.
+2. Exercise the changed tool path against the local server or development setup.
+3. Confirm the normalized output shape is sensible.
+4. Clean up all temporary Linear data before finishing.
+
+If live validation cannot run:
+
+- report the exact blocker
+- state whether build/test validation still passed
+- identify whether the remaining risk is configuration, SDK, or live schema behavior
+
+When a live failure occurs, distinguish between:
+
+- local repo regression
+- stale or broken SDK query
+- workspace/schema-specific Linear behavior

.github/agents/mcp-release-manager.agent.md

@@ -0,0 +1,24 @@
+---
+name: mcp-release-manager
+description: Prepares versioning and release changes for the mcp-linear package and publish workflow.
+tools: ["read", "search", "edit", "execute", "github/*"]
+disable-model-invocation: true
+---
+
+You manage release-oriented changes for `mcp-linear`.
+
+Repository-specific release facts:
+
+- Package name: `@itz4blitz/mcp-linear`
+- Publish workflow: `.github/workflows/publish.yml`
+- Publish workflow runs `npm ci`, `npm test`, and `npm run build` before versioning and publishing.
+- The workflow performs `npm version ... -m "Bump version to %s [skip ci]"`.
+
+Responsibilities:
+
+1. Verify release readiness by checking tests, build, docs, and public tool surface updates.
+2. Keep version bumps and release metadata scoped and explicit.
+3. Check whether `TOOLS.md`, `README.md`, or `package.json` need release-related updates.
+4. Avoid publishing or triggering release workflows unless explicitly requested.
+
+When summarizing release readiness, call out user-facing tool additions and any SDK workarounds that downstream consumers should know about.

.github/copilot-instructions.md

@@ -0,0 +1,38 @@
+# MCP Linear Repository Instructions
+
+This repository is an MCP server for Linear, not an application. Most work in this repo adds, updates, or reviews Linear-facing MCP tools.
+
+## Repository Map
+
+- `src/services/linear-service.ts`: main integration layer for `@linear/sdk` and the place where MCP-facing response normalization should happen.
+- `src/tools/definitions/*.ts`: MCP tool definitions and input/output schemas, grouped by domain.
+- `src/tools/handlers/*.ts`: thin handlers that validate arguments, delegate to `LinearService`, and log errors.
+- `src/tools/type-guards.ts`: runtime validation for tool arguments.
+- `src/tools/definitions/index.ts` and `src/tools/handlers/index.ts`: central registration.
+- `src/__tests__/*.ts`: focused Jest coverage for service behavior and tool wiring.
+- `TOOLS.md`: user-facing tool inventory and planned work.
+- `package.json`: package metadata.
+
+## How To Add Or Change A Tool
+
+- Start by checking whether the capability already exists in `src/services/linear-service.ts`.
+- Prefer `@linear/sdk` methods and generated types first.
+- Use direct GraphQL only when the SDK is missing support or ships a stale query. If you do this, keep the query narrow and document why.
+- Keep service methods responsible for returning normalized plain objects, not raw SDK entities.
+- Keep handlers thin.
+- Keep `input_schema`, `output_schema`, type guards, and normalized service output aligned exactly, especially around nullable fields and enums.
+- Register every new tool in both index files.
+- Update `TOOLS.md` when the public tool surface changes.
+
+## Validation
+
+- Always run `npm test` and `npm run build` before considering work complete.
+- Use `npm run dev -- --token YOUR_LINEAR_API_TOKEN` for local server development.
+- Use `npm run inspect -- -e LINEAR_API_TOKEN=YOUR_LINEAR_API_TOKEN` when validating the local MCP server with the inspector.
+
+## Project-Specific Pitfalls
+
+- This repo frequently needs careful SDK contract inspection. Check `node_modules/@linear/sdk/dist/_generated_sdk.d.ts` and `_generated_documents.d.ts` before guessing field names or mutation inputs.
+- Some Linear product naming does not match SDK naming. For example, saved views are `CustomView` in the API and SDK.
+- Review changes carefully for schema drift between service output, tool definitions, and type guards.
+- Keep changes minimal and domain-local. Prefer extending an existing domain file over introducing new structure unless the domain is clearly separate.

.github/instructions/review.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: "**"
+excludeAgent: "cloud-agent"
+---
+
+When reviewing pull requests in this repository, focus on MCP contract correctness first.
+
+- Prioritize findings about schema drift, runtime validation mismatches, missing registration, broken normalization, and missing tests.
+- Compare `output_schema` to the actual service output, especially around nullable fields.
+- Compare `input_schema` to the corresponding type guard and handler assumptions.
+- Check that new public tools are registered in both index files and listed in `package.json` and `TOOLS.md` when appropriate.
+- Flag direct GraphQL usage that does not clearly justify why the SDK path was insufficient.
+- Present findings first, with file references and severity ordering.

.github/instructions/service.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: "src/services/**/*.ts"
+---
+
+This repository uses `src/services/linear-service.ts` as the single integration layer for Linear.
+
+- Prefer `@linear/sdk` methods and generated types before writing direct GraphQL.
+- If you must bypass the SDK, use `this.client.client.request(...)` with the narrowest query that satisfies the tool contract and explain why the SDK path was not used.
+- Normalize returned SDK entities into plain objects before returning them to handlers.
+- Keep response shapes honest about `null`, `undefined`, enums, and date handling.
+- Preserve explicit clearing semantics when the Linear API supports `null` for updates.
+- Throw precise errors that identify the entity or operation that failed.
+- Reuse helper functions for compacting inputs and handling nullable fields instead of open-coding one-off sanitization.

.github/instructions/tests.instructions.md

@@ -0,0 +1,12 @@
+---
+applyTo: "src/__tests__/**/*.ts"
+---
+
+Tests in this repository should be focused and MCP-specific.
+
+- Add narrow tests around the behavior introduced by the change instead of broad snapshots.
+- Cover at least one positive path and one negative or validation path for new tool surfaces.
+- When a service method uses a direct GraphQL fallback, test the expected normalized shape and any filtering logic.
+- When update inputs support `null` clearing, add a test that preserves explicit `null` values.
+- When schemas or guards add constraints like enums or positive integers, add tests that reject invalid values.
+- Prefer mocking the smallest possible surface of the Linear client or `LinearService` dependency needed for the scenario.

.github/instructions/tool-definitions.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: "src/tools/definitions/**/*.ts,src/tools/handlers/**/*.ts,src/tools/type-guards.ts"
+---
+
+Changes in the MCP surface must keep definitions, handlers, and guards aligned.
+
+- `input_schema`, type guards, and handler expectations must use the same field names and required fields.
+- `output_schema` must match the actual normalized service output, including nullable objects, nullable strings, enums, and numeric constraints.
+- Prefer explicit enums and positive integer constraints over generic `string` or `number` schemas when the contract is known.
+- Handlers in this repo should stay thin: validate, delegate to `LinearService`, and log failures.
+- Every new public tool must be registered in both `src/tools/definitions/index.ts` and `src/tools/handlers/index.ts`.
+- If the tool is intended for external clients, update `TOOLS.md` in the same change.
+- Call out API naming mismatches directly in descriptions when needed, such as Linear saved views being exposed as `CustomView` in the SDK.

.github/prompts/implement-mcp-tool.prompt.md

@@ -0,0 +1,20 @@
+Add or update an MCP tool in the `mcp-linear` repository.
+
+Requirements:
+
+- Inspect existing patterns before editing.
+- Check `@linear/sdk` before writing direct GraphQL.
+- Implement or update the service method in `#file:../../src/services/linear-service.ts`.
+- Wire the full MCP surface:
+  - tool definitions in `#file:../../src/tools/definitions/index.ts`
+  - handlers in `#file:../../src/tools/handlers/index.ts`
+  - runtime validation in `#file:../../src/tools/type-guards.ts`
+- Update `#file:../../TOOLS.md`.
+- Add focused tests under `#file:../../src/__tests__/linear-service.test.ts` or a new adjacent test file.
+- Run `npm test` and `npm run build`.
+
+Quality bar:
+
+- Keep output normalization honest about nullability.
+- Keep handlers thin.
+- Explain any SDK fallback to direct GraphQL.