affinity-mcp-proxy

affinity-mcp-proxy exposes the local Affinity MCP server as an MCP server over stdio.

It is designed for tools that know how to launch MCP servers as local commands, for example:

{
  "mcpServers": {
    "affinity": {
      "command": "pnpm",
      "args": ["dlx", "affinity-mcp-proxy"]
    }
  }
}

What it does

• connects to the local Affinity MCP server over HTTP/SSE
• re-exposes tools/list and tools/call over stdio
• primes execute_script with read_preamble in the same upstream session
• ships a small CLI for diagnostics and direct tool calls

Status

• first-class target: macOS
• runtime: Node.js 22+
• package manager: pnpm

Other platforms may work, but this package is only validated on macOS in the first release.

Install and run

Preferred ephemeral usage:

pnpm dlx affinity-mcp-proxy

Direct CLI usage:

pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli list-tools
pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli call-tool search_sdk_hints '{"query":"text style"}'

Local development:

pnpm install
pnpm test
pnpm dlx . --help
node ./affinity_mcp_proxy.mjs --help

Requirements

• Affinity must be open
• the local Affinity MCP server must be enabled and listening
• Node.js 22 or newer

By default the proxy tries these upstream URLs:

• http://127.0.0.1:6767/sse
• http://127.0.0.1:6767
• http://[::1]:6767/sse
• http://[::1]:6767

Environment variables

• AFFINITY_MCP_URL
  • force a specific upstream MCP URL
• AFFINITY_MCP_CONNECT_TIMEOUT_MS
  • override the connection timeout
• AFFINITY_MCP_DEBUG
  • enable proxy debug logs on stderr

The proxy requires the SDK to be installed through the package dependencies. There is no alternate local SDK fallback.

Commands

Proxy server:

pnpm dlx affinity-mcp-proxy
pnpm dlx affinity-mcp-proxy --help
pnpm dlx affinity-mcp-proxy --version

Diagnostic CLI:

pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli list-tools
pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli execute-script-file ./script.js
pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli render-spread-file DOCUMENT_SESSION_UUID '{"spread_index":2,"out":"/tmp/spread-2.jpg"}'

Troubleshooting

If the proxy exits immediately:

• confirm Affinity is open
• confirm the local MCP endpoint is enabled
• set AFFINITY_MCP_DEBUG=1 to see connection attempts
• if your environment prefers a specific interface, set AFFINITY_MCP_URL explicitly

If text formatting scripts fail inside Affinity with COMMAND_FAILED, make sure the script sets the current spread to the target text node spread before calling doc.formatText(...).