# @kody/linear-mcp — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke execute snippets, and edge cases. Never paste tokens.
Do not disable live webhooks or jobs. After a fork, connect **the caller's**
Linear workspace — do not reuse the live `@kody/linear-mcp` connection.

## Auth / MCP

| Item | Value |
| --- | --- |
| MCP server name | `linear` (not `linear-mcp`) |
| MCP URL | `https://mcp.linear.app/mcp` |
| Runtime | `kody.mcp["linear"]` |
| OAuth/API fallback | `@kody/linear` — https://kody.codes/@kody/linear |

Add + authorize:

```js
import { kody } from 'kody:runtime'

export default async function main() {
	return await kody.mcpServerAdd({
		name: 'linear',
		url: 'https://mcp.linear.app/mcp',
	})
	// Open returned authUrl, then re-run smoke-test
}
```

## Import paths

| Export | Import |
| --- | --- |
| overview / setup status | `kody:@kody/linear-mcp` |
| smoke-test | `kody:@kody/linear-mcp/smoke-test` |
| list-issues | `kody:@kody/linear-mcp/list-issues` |

Prefer static `kody:@kody/linear-mcp/...` imports from `execute`. Do not lead
with `packages.invoke`. Prefer `@kody/linear` once BYO OAuth or an API key is
ready — this package is the faster first-win MCP path.

## Smoke test (read-only)

```js
import smokeTest from 'kody:@kody/linear-mcp/smoke-test'

export default async function main() {
	return await smokeTest()
	// not connected => { ok: true, live: false, setup: { mcp, oauthApiFallback } }
	// connected => { ok: true, live: true, via: 'mcp', tool }
}
```

Overview (no Linear call beyond local MCP status):

```js
import linearMcp from 'kody:@kody/linear-mcp'

export default async function main() {
	return await linearMcp()
}
```

## Common snippets

```js
import listIssues from 'kody:@kody/linear-mcp/list-issues'

export default async function main() {
	return await listIssues({ limit: 10 })
	// optional: { query: 'checkout timeout', limit: 20 }
}
```

## Edge cases / fork notes

- MCP *server* name is always `linear`; package id is `linear-mcp`.
- `list-issues` throws the setup message when MCP is not connected.
- Tool-name probing tries several Linear MCP tool ids (`list_issues`,
  `listIssues`, …) — do not hard-code a single vendor tool name in callers.
- Do not treat the platform `@kody/linear-mcp` connection as the caller's
  workspace after a fork.
- For GraphQL OAuth / personal API key helpers, mutations with `dryRun` /
  `confirm`, use `@kody/linear` instead.