mcp-cogview

# 1. 安装依赖
npm install

# 2. 配置 API Key（任选其一填到 .env）
#    也可以直接在 .env 里填 ZHIPU_API_KEY=sk-xxxx
cp .env.example .env
# Windows CMD:        notepad .env
# Windows PowerShell: code .env   （或任意编辑器）

# 3. 启动
npm start            # 加载 .env，启动 http://127.0.0.1:3000
npm run start:mock   # 强制 mock 模式（即使填了 Key 也不调用真实 API）
npm run start:real   # 强制真实模式（缺 Key 时返回 401 而不是 mock）
npm run verify       # 端到端验证（自身强制 mock，29 项断言）
npm run typecheck    # 类型检查
npm run dev          # 热重载开发

src/
├── framework/                # 与业务无关的框架层（沿用 starter）
│   ├── types.ts              # McpModule / ModuleContext / ServerConfig 等契约
│   ├── logger.ts             # JSON 行结构化日志
│   ├── event-store.ts        # 内存事件存储（Last-Event-ID 断线续传）
│   ├── app.ts                # 核心：模块注册表 + 会话管理 + 传输层装配
│   └── http.ts               # Express 路由：MCP 端点 + live/ready 探针 + CORS
├── modules/
│   ├── live.ts               # live 健康检查模块（tool + resource + prompt）
│   ├── cogview-client.ts     # 智谱 CogView 文生图 API 客户端（fetch + 异步轮询）
│   └── cogview.ts            # CogView MCP 模块：generate_image 工具 + 模型清单资源
├── config.ts                 # 服务配置 + CogView 模块配置
├── server.ts                 # 组装与启动
└── index.ts                  # 进程入口 + 信号处理
scripts/verify.ts             # 端到端验证脚本（mock 模式自动启用）

{
  "status": "live",
  "service": "mcp-cogview",
  "version": "0.1.0",
  "protocol": "streamable-http",
  "uptimeMs": 16048,
  "startedAt": "2026-08-05T01:43:00.213Z",
  "pid": 8780,
  "sessions": { "active": 0, "created": 1 },
  "requestsTotal": 7,
  "toolCalls": 2,
  "memory": { "rssMB": 79.1, "heapUsedMB": 22.4, "heapTotalMB": 24 },
  "modules": [
    { "name": "live", "version": "1.0.0" },
    { "name": "cogview", "version": "1.0.0" }
  ],
  "endpoints": { "mcp": "/mcp", "live": "/live", "...": "..." }
}

{
  "created": 1754361600,
  "model": "cogview-3-plus",
  "size": "1024x1024",
  "images": [
    { "url": "https://...", "b64Bytes": null, "mimeType": "image/png" }
  ],
  "usage": { "promptTokens": 12, "completionTokens": null, "totalTokens": null },
  "mock": false
}

claude mcp add --transport http cogview http://127.0.0.1:3000/mcp

# 0. 启动服务（写入 .env 后，无需手动 set/export）
#    .env 里有 ZHIPU_API_KEY=sk-xxxxxxxx
npm start &

# 1. 存活探针
curl -s http://127.0.0.1:3000/live | jq

# 2. initialize（从响应头取 Mcp-Session-Id）
SID=$(curl -s -D - -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
  | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}' | tr -d '\r')

curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. 列出可用模型
curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"cogview://models"}}'

# 4. 文生图
curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"generate_image","arguments":{"prompt":"赛博朋克少女，霓虹背景","size":"1024x1024"}}}'

// src/modules/echo.ts
import { z } from 'zod';
import type { McpModule } from '../framework/types.js';

export const echoModule: McpModule = {
    name: 'echo',
    version: '1.0.0',
    register(server, ctx) {
        server.registerTool(
            'echo',
            { description: '回显输入', inputSchema: { text: z.string() } },
            async ({ text }) => {
                ctx.markToolCall();
                return { content: [{ type: 'text', text }] };
            }
        );
    }
};