# streamlinear

A lightweight Linear MCP for Claude Code. One tool, seven actions.

## Why?

The standard Linear MCP uses ~17,000 tokens for tool definitions.

streamlinear uses ~500 tokens.

## Design Philosophy

Instead of 23 separate tools, streamlinear has **one tool with action dispatch**:

```json
{"action": "search"}
{"action": "get", "id": "ABC-123"}
{"action": "update", "id": "ABC-123", "state": "Done"}
{"action": "comment", "id": "ABC-123", "body": "Fixed!"}
{"action": "create", "title": "New bug", "team": "ENG"}
{"action": "graphql", "graphql": "query { viewer { name } }"}
{"action": "help"}
```

## Actions

| Action | Purpose |
|--------|---------|
| `search` | Find issues (smart defaults: your active issues) |
| `get` | Issue details by ABC-123, URL, or UUID |
| `update` | Change state, priority, assignee |
| `comment` | Add comment to issue |
| `create` | Create new issue |
| `graphql` | Raw GraphQL for anything else |
| `help` | Full documentation |

## Installation

### Single Workspace

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@primeradianthq/streamlinear@1.1.3"],
      "env": {
        "LINEAR_API_TOKEN": "lin_api_xxxxx"
      }
    }
  }
}
```

### Multiple Workspaces

To use streamlinear with multiple Linear workspaces, create separate MCP entries and map each secret to `LINEAR_API_TOKEN`:

```json
{
  "mcpServers": {
    "linear-personal": {
      "command": "npx",
      "args": ["-y", "@primeradianthq/streamlinear@1.1.3"],
      "env": {
        "LINEAR_API_TOKEN": "${LINEAR_PERSONAL_TOKEN}"
      },
      "envFrom": ["LINEAR_PERSONAL_TOKEN"]
    },
    "linear-work": {
      "command": "npx",
      "args": ["-y", "@primeradianthq/streamlinear@1.1.3"],
      "env": {
        "LINEAR_API_TOKEN": "${LINEAR_WORK_TOKEN}"
      },
      "envFrom": ["LINEAR_WORK_TOKEN"]
    }
  }
}
```

### Installed Package

When installed as a dependency, the package provides two binaries:

```bash
npm install @primeradianthq/streamlinear@1.1.3
npx streamlinear-cli help
npx streamlinear
```

The MCP server requires `LINEAR_API_TOKEN` at runtime. Consumers such as Scribble may expose their own operator-facing variable and map it to `LINEAR_API_TOKEN` before starting streamlinear.

## Smart Defaults

- Teams and workflow states shown in tool description (fetched at startup)
- `search` with no params → your assigned issues, not completed/canceled
- IDs accept ABC-123, Linear URLs, or UUIDs
- State names are fuzzy matched ("done" → "Done", "in prog" → "In Progress")
- `assignee: "me"` uses the authenticated user
- Error messages show valid options when things fail

## The GraphQL Escape Valve

For anything not covered by the main actions, use raw GraphQL:

```json
{
  "action": "graphql",
  "graphql": "query { projects { nodes { id name } } }"
}
```

Use `{"action": "help"}` for common GraphQL patterns.

## License

MIT