cysic-mcp

A Model Context Protocol (MCP) server in TypeScript/Node.js that exposes the Cysic AI model (minimax-m3) to any MCP client over stdio, with server-side session memory and a tone-rewriting tool.

Problem

AI assistants and other MCP clients need a uniform way to call an LLM, manage multi-turn conversations across many requests, and rewrite text in different tones — but most existing LLM SDKs are HTTP-first and require per-integration boilerplate. A Cysic AI user has to:

1. Wire axios (or fetch) with the right Authorization: Bearer … header.
2. Implement retry/backoff for 429 / 5xx / network failures.
3. Validate every tool input with zod so a misbehaving client cannot crash the server.
4. Manage session state for multi-turn chat.
5. Plug the whole thing into their MCP client.

cysic-mcp collapses all five into a single npm install + one configuration file.

Solution

cysic-mcp is a single, small Node.js process that speaks the MCP stdio transport. It registers exactly:

• 3 tools: cysic_chat, cysic_session, cysic_humanize
• 2 resources: cysic://models, cysic://sessions/{id}
• 2 prompts: code_review, humanize_text

…and nothing more. The HTTP layer is a typed CysicClient wrapper around axios with explicit timeout + exponential-backoff retries. All tool inputs are validated by zod. All configuration is environment-driven; the server fails fast at startup if the required CYSIC_API_KEY is missing.

Feature Checklist

The shipped surface, one item per row:

• [x] Tool: cysic_chat { prompt, system?, temperature? } — single-turn chat with the Cysic AI model. prompt is required (min length 1); system overrides the default "You are a helpful assistant." preamble; temperature is optional in [0, 2].
• [x] Tool: cysic_session { session_id, message } — multi-turn chat with server-side history. The server keeps the full conversation per session_id in an in-process Map; each call sends the entire history to the model and appends the assistant reply. Sessions are created lazily on first use.
• [x] Tool: cysic_humanize { text, tone? } — rewrite text in a requested tone. tone defaults to neutral and accepts neutral | friendly | formal | concise | confident. Internally uses a tone-specific system prompt and a low sampling temperature (0.2 for concise, 0.4 otherwise) to keep rewrites stable.
• [x] Resource: cysic://models — static catalog of models served by this MCP server, rendered as a JSON text/plain payload (e.g. { models: [{ id: "minimax-m3", provider: "cysic", default: true }] }).
• [x] Resource: cysic://sessions/{id} — read template for a single session's message history. The {id} path segment is the session_id. Returns the JSON-serialized message array; missing sessions return [].
• [x] Prompt: code_review { language?, code } — render a senior-level code-review prompt for a code snippet. language is optional (e.g. "TypeScript"); code is required. The prompt returns two messages the client can render as a chat template.
• [x] Prompt: humanize_text { tone?, text } — render a prompt that mirrors the cysic_humanize tool contract so an MCP client can present it as a chat template without invoking the tool.

Distinctive features (innovation callouts):

• [x] Server-side session memory — cysic_session keeps a per-id Map<string, Message[]> so the client does not have to round-trip history. History is in-process; sessions are lost on restart and are not shared across processes (acceptable for a single-instance stdio MCP server).
• [x] cysic_humanize tone rewriting — five built-in tones (neutral, friendly, formal, concise, confident), each with its own instruction string and temperature. The same tone vocabulary is reused by the humanize_text prompt so the prompt and the tool stay in lock-step.

Architecture

+----------------------+        stdio JSON-RPC        +------------------+
|  MCP client (e.g.    |  <-------------------------->  |  cysic-mcp      |
|  Claude Desktop,     |                              |  (Node.js)       |
|  any stdio MCP host) |                              |                  |
+----------------------+                              |  src/server.ts   |
                                                     |   |              |
                                                     |   v              |
                                                     |  src/tools/      |
                                                     |  src/resources/  |
                                                     |  src/prompts/    |
                                                     |   |              |
                                                     |   v              |
                                                     |  CysicClient     |
                                                     |  (axios + retry) |
                                                     +--------+---------+
                                                              |
                                                              v
                                                  POST /v1/chat/completions
                                                  https://token-ai.cysic.xyz

Project layout

src/
  server.ts            # MCP server bootstrap, transport wiring
  config.ts            # env loading (loadConfig)
  cysicClient.ts       # axios wrapper + retry/backoff
  state.ts             # in-process session Map (sessions)
  errors.ts            # CysicError + toMcpErrorMessage sanitizer
  tones.ts             # shared tone vocabulary (used by tool + prompt)
  mcpShims.ts          # untyped SDK registration shims
  tools/
    index.ts           # registerTools(server, client, state)
    cysicChat.ts       # cysic_chat tool
    cysicSession.ts    # cysic_session tool
    cysicHumanize.ts   # cysic_humanize tool
  resources/
    index.ts           # registerResources(server, state)
    models.ts          # cysic://models resource
    session.ts         # cysic://sessions/{id} resource template
  prompts/
    index.ts           # registerPrompts(server)
    codeReview.ts      # code_review prompt
    humanizeText.ts    # humanize_text prompt
tests/
  cysicClient.test.ts  # 8 tests (a-e per AC-3, plus a few extras)
  structure.test.ts    # 5 tests defending the AC-5 module split
dist/                  # tsc output (gitignored)

Install

cysic-mcp requires Node.js >= 18.17 (for native fetch / AbortController; we still use axios per the project rubric for explicit timeout + retry control).

git clone <this-repo> cysic-mcp
cd cysic-mcp
npm install
npm run build

The build emits dist/server.js, which is the entry point referenced by the start script and the cysic-mcp bin.

Configure

Copy the example env file and fill in your real Cysic API key:

cp .env.example .env
# then edit .env and set CYSIC_API_KEY=...

The full set of environment variables:

Variable	Required	Default	Description
CYSIC_API_KEY	yes	—	Bearer token for the Cysic AI endpoint. Never echoed in logs.
CYSIC_BASE_URL	no	https://token-ai.cysic.xyz/v1	Base URL for the Cysic AI OpenAI-compatible API.
CYSIC_MODEL	no	minimax-m3	Default model used by the tools when no per-call override is given.
CYSIC_TIMEOUT_MS	no	30000	Per-request HTTP timeout in milliseconds.
CYSIC_MAX_RETRIES	no	3	Retries on 429 / 5xx / network errors (exponential backoff + jitter).

If CYSIC_API_KEY is missing or empty, the server fails fast at startup with a clear error message that names the variable (but does not echo the value).

Run

Production (after npm run build):

npm start
# equivalent to:  node dist/server.js

Development (live TypeScript via tsx):

npm run dev
# equivalent to:  tsx src/server.ts

The server uses the MCP stdio transport. There is no HTTP port to scrape; stdout is reserved for the MCP JSON-RPC stream. All fatal startup errors are written to stderr so they do not corrupt the MCP channel.

MCP Client Registration

Point your MCP client at the compiled entry point. The exact JSON shape depends on the client; the two common forms are below.

Claude Desktop (claude_desktop_config.json)

Add this entry under mcpServers:

{
  "mcpServers": {
    "cysic": {
      "command": "node",
      "args": ["/absolute/path/to/cysic-mcp/dist/server.js"],
      "env": {
        "CYSIC_API_KEY": "sk-your-real-key-here"
      }
    }
  }
}

If you prefer the .env file approach, omit the env block and let the server read it from disk:

{
  "mcpServers": {
    "cysic": {
      "command": "node",
      "args": ["/absolute/path/to/cysic-mcp/dist/server.js"]
    }
  }
}

Generic stdio MCP config

Any MCP host that speaks stdio can launch the server as a child process. The minimum invocation is:

{
  "command": "node",
  "args": ["dist/server.js"],
  "cwd": "/absolute/path/to/cysic-mcp",
  "env": {
    "CYSIC_API_KEY": "sk-your-real-key-here",
    "CYSIC_BASE_URL": "https://token-ai.cysic.xyz/v1",
    "CYSIC_MODEL": "minimax-m3"
  }
}

For a development-mode build, swap node + dist/server.js for npx tsx src/server.ts and the host will run the TypeScript source directly.

Example Tool Calls

The examples below are copy-pasteable. The exact wire format depends on your MCP client; the JSON argument shape is what the server validates with zod.

cysic_chat — single-turn chat

{
  "name": "cysic_chat",
  "arguments": {
    "prompt": "What is the capital of France?",
    "system": "You are a concise geography tutor.",
    "temperature": 0.2
  }
}

Returns:

{
  "content": [{ "type": "text", "text": "Paris." }],
  "isError": false
}

cysic_session — multi-turn chat with server-side history

Turn 1:

{
  "name": "cysic_session",
  "arguments": {
    "session_id": "user-42",
    "message": "Hi, my name is Alice."
  }
}

Turn 2 (the server sends the full [user, assistant, user] history to the model):

{
  "name": "cysic_session",
  "arguments": {
    "session_id": "user-42",
    "message": "What's my name?"
  }
}

The full history can be inspected at runtime by reading the cysic://sessions/user-42 resource.

cysic_humanize — tone rewriting

{
  "name": "cysic_humanize",
  "arguments": {
    "text": "We're gonna ship the thing on Friday. Probably.",
    "tone": "formal"
  }
}

tone defaults to neutral; the full set of accepted values is neutral | friendly | formal | concise | confident.

cysic://models — model catalog

{ "uri": "cysic://models" }

Returns a JSON payload listing the Cysic AI models served by this server (currently { id: "minimax-m3", provider: "cysic", default: true }).

cysic://sessions/{id} — per-session history

{ "uri": "cysic://sessions/user-42" }

Returns the JSON-serialized message array for user-42. Missing sessions return [].

code_review prompt

{
  "name": "code_review",
  "arguments": {
    "language": "TypeScript",
    "code": "const x: number = 1; console.log(x);"
  }
}

Renders two messages the client can show as a chat template: a "you are a senior TypeScript engineer…" brief and a fenced code block to review.

humanize_text prompt

{
  "name": "humanize_text",
  "arguments": {
    "tone": "confident",
    "text": "I think maybe we could try to ship this?"
  }
}

Renders two messages that mirror the cysic_humanize tool contract (the tone instruction as the first message, the text to rewrite as the second). Because the MCP PromptMessage.role enum is restricted to "user" | "assistant", both messages are emitted with role: "user"; the "system" intent from the plan is preserved by the two-message shape, not by a literal role: "system".

Testing

Unit tests use vitest and stub the HTTP layer with nock so no real network is ever made.

npm test

The current suite covers:

• tests/cysicClient.test.ts — 8 tests across the AC-3 cases (a) 200 returns first choice, (b) 429 retried then succeeds, (c) 500 retried then fails with no apiKey in the message, (d) 400 fails fast with code: BAD_REQUEST and is not retried, (e) request body includes model and messages, plus extras for temperature pass-through, per-call model override, and empty-messages rejection.
• tests/structure.test.ts — 5 tests importing every per-feature registerX function and the CysicError / toMcpErrorMessage / TONE_VALUES / temperatureForTone / TONE_INSTRUCTIONS exports from the compiled dist/ tree, to defend the AC-5 module split.

License

MIT