@kualat/mcp

A Model Context Protocol server for a kua.lat installation: shorten links, read click statistics, and manage signed webhook subscriptions from an AI assistant.

Written in TypeScript on top of the official @modelcontextprotocol/sdk. The server holds no state and stores no credentials; it authenticates to your installation with a bearer API key on every request.

Requirements

• Node.js 18 or newer

• Network access to your installation

Related MCP server: mcp-shlink

Install

npm install -g @kualat/mcp

The kualat-mcp command is then on your path. To run it without installing:

npx -y @kualat/mcp --version

Configure a client

Add the server to claude_desktop_config.json for Claude Desktop, or to mcp.json for Cursor and other clients that launch stdio servers:

{
  "mcpServers": {
    "kualat": {
      "command": "kualat-mcp",
      "env": {
        "KUALAT_API_URL": "https://your-domain.com/api",
        "KUALAT_API_KEY": "your-api-key"
      }
    }
  }
}

If the binary is not on the client's PATH, use "command": "npx" with "args": ["-y", "@kualat/mcp"], or pass the values as flags: "args": ["--api-url=https://your-domain.com/api", "--api-key=..."].

Scopes on the key decide which tools work: links covers the link tools, domains covers list_domains, webhooks covers the webhook tools, and all covers everything.

Tools

Every tool declares MCP annotations: readOnlyHint for reads, destructiveHint for delete_link and delete_webhook, and openWorldHint because each call reaches your installation over the network. Argument schemas are built with zod, so invalid arguments are rejected before the API is called.

update_link follows the API's PATCH semantics: fields that are not sent are cleared. Pass every field you want to keep.

Protocol behaviour

• Built on the official SDK: stdio transport, initialize handshake and protocol version negotiation are handled there.

• Advertises the tools capability only. No resources, prompts or sampling.

• Tool failures (HTTP errors, missing arguments) return isError: true with the API's detail text, so the assistant can correct itself instead of seeing a protocol error.

• Notifications never receive a response.

• stdout carries JSON-RPC only. Diagnostics go to stderr.

Command line

kualat-mcp --version
kualat-mcp --list-tools
kualat-mcp --call '{"name":"list_links","arguments":{"limit":2}}'
kualat-mcp --call '{"name":"shorten_link","arguments":{"url":"https://example.com"}}'

--call runs the request through the same server implementation a client talks to, so its output matches the protocol. With neither --list-tools nor --call, the server speaks MCP over stdin/stdout:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | kualat-mcp

Development

npm install
npm run lint          # tsc --noEmit
npm run check         # build + smoke test over an in-memory transport, no network

Layout:

src/cli.ts       argument parsing, --list-tools/--call, stdio entry point
src/server.ts    McpServer assembly and tool registration
src/tools.ts     tool catalog: zod schemas, annotations, handlers
src/client.ts    HTTP client over fetch
src/errors.ts    ApiError
src/version.ts   server name and version

Security

• The server acts with the privileges of the API key it is given. Create a scoped key when the assistant only needs part of the catalog.

• Destructive tools are annotated but not gated here; the client decides whether to ask. Treat a key handed to an autonomous agent as a key that can delete links.

• Nothing is written to disk. Keep the key in the client configuration.

License

MIT. See LICENSE.