npm package: @inkwren/mcp-server
Description: Inkwren MCP server — exposes catalog tools via Model Context Protocol
Latest version: 0.1.2

# Inkwren MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes Inkwren's catalog tools to AI assistants like Claude Code. Query your stories, submissions, publications, tasks, and more directly from your AI workflow.

The MCP server is a thin protocol bridge — it discovers tools from the Inkwren API at startup and proxies tool calls through authenticated endpoints. All query logic and data access runs server-side with full RLS scoping.

## Prerequisites

- Node.js >= 18
- An Inkwren account with the **API Keys** feature enabled (admin-controlled)

## Getting an API Key

1. Log in to Inkwren and navigate to **Workspace Settings**
2. Click the **API Keys** tab
3. Click **Create API Key**
   - **Name**: A label for this key (e.g., "Claude Code MCP")
   - **Scopes**: Select both **Read** and **Write** (Write is required because tool execution uses POST requests)
   - **Expiry**: Choose an expiration period (1 year recommended)
4. Copy the full `ink_...` key immediately — it is shown only once

## Configuration

The MCP server requires two environment variables:

| Variable | Description | Example |
|----------|-------------|---------|
| `INKWREN_API_URL` | Inkwren API base URL | `https://app.inkwren.com/api` |
| `INKWREN_AUTH_TOKEN` | Your API key (must start with `ink_`) | `ink_a1b2c3...` |

The API key is workspace-scoped: it determines which workspace's data you can access. If you work with multiple workspaces, create a separate key for each.

## Adding to Claude Code

**Step 1: Set your API key in your shell profile** (`.zshenv` recommended — works in all contexts, not just interactive shells):

```bash
export INKWREN_AUTH_TOKEN=ink_your_key_here
```

**Step 2: Register the MCP server** using the CLI (recommended):

```bash
claude mcp add-json inkwren --scope project '{"type":"stdio","command":"npx","args":["@inkwren/mcp-server"],"env":{"INKWREN_API_URL":"https://app.inkwren.com/api","INKWREN_AUTH_TOKEN":"${INKWREN_AUTH_TOKEN}"}}'
```

Use `--scope user` instead of `--scope project` to make the server available across all projects.

**Alternative: `.mcp.json` file**

Create a `.mcp.json` file in your project root:

```json
{
  "mcpServers": {
    "inkwren": {
      "type": "stdio",
      "command": "npx",
      "args": ["@inkwren/mcp-server"],
      "env": {
        "INKWREN_API_URL": "https://app.inkwren.com/api",
        "INKWREN_AUTH_TOKEN": "${INKWREN_AUTH_TOKEN}"
      }
    }
  }
}
```

Note: `.mcp.json` is only read if no existing entry for the server exists in your Claude Code configuration. If you previously registered the server via `claude mcp add`, the `.mcp.json` entry will be ignored. Use `claude mcp add-json` to update an existing registration.

## Available Tools

The server registers 20 tools (19 catalog tools discovered from the API + 1 utility):

**Utility:**
- `inkwren_list_workspaces` — List all workspaces you have access to

**Stories:**
- `inkwren_search_stories` — Search and filter stories
- `inkwren_find_unsubmitted_stories` — Find stories not currently submitted anywhere
- `inkwren_get_story_details` — Get full details for a specific story

**Submissions:**
- `inkwren_search_submissions` — Search submissions with filters
- `inkwren_get_acceptance_rate` — Get acceptance rate statistics
- `inkwren_get_response_times` — Get average response time data
- `inkwren_get_pending_submissions` — List submissions awaiting response

**Publications:**
- `inkwren_search_publications` — Search and filter publications
- `inkwren_get_publication_timeline` — Get upcoming publication dates

**Rights & Contracts:**
- `inkwren_get_rights_for_story` — Get rights information for a story
- `inkwren_get_expiring_rights` — Find rights nearing expiration
- `inkwren_search_contracts` — Search contracts

**Markets:**
- `inkwren_get_markets` — List markets with stats
- `inkwren_get_market_stats` — Get detailed market statistics

**Tasks:**
- `inkwren_search_tasks` — Search and filter tasks
- `inkwren_create_task` — Create a new task
- `inkwren_update_task` — Update an existing task

**Submissions (Write):**
- `inkwren_update_submission_status` — Update a submission's status

**Overview:**
- `inkwren_get_catalog_summary` — Counts of stories, publications, tasks, and more

> **Note:** Write tools (`create_task`, `update_task`, `update_submission_status`) require the `ai-write-tools` feature flag to be enabled by an admin. When the flag is off, these tools are excluded from discovery and calls return 403.

## Available Resources

One MCP resource provides at-a-glance workspace context (live query, no caching):

| Resource URI | Description |
|-------------|-------------|
| `inkwren://workspace/summary` | Counts of stories, publications, tasks, active projects |

Other workspace data (upcoming tasks, pending submissions) is available on demand via the `inkwren_search_tasks` and `inkwren_get_pending_submissions` tool calls — no need to burn tokens loading them on every session.

## Error Messages

The server translates API errors to human-readable messages:

| HTTP Status | Message |
|-------------|---------|
| 401 | Authentication expired or invalid. Please update your INKWREN_AUTH_TOKEN. |
| 403 | You do not have permission to perform this action. |
| 429 | Rate limited. Please wait a moment and try again. |
| 500 | Inkwren server error. Please try again later. |
| 502/503/504 | Inkwren is temporarily unavailable. Please try again in a few minutes. |

## Troubleshooting

If tool discovery fails on startup (API unavailable), the server starts with only `inkwren_list_workspaces` and the workspace summary resource. Check your `INKWREN_API_URL` and `INKWREN_AUTH_TOKEN` values.

Successful startup prints to stderr:
```
Inkwren MCP server ready (19 catalog tools + 1 utility tool + 1 resource)
```