Back to Details

install-mcpcat-typescript

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Installing MCPCat Analytics SDK

安装MCPCat Analytics SDK

Overview

概述

MCPCat is a one-line analytics integration for MCP servers. Call 
mcpcat.track(server, projectId)
to capture tool usage patterns, user intent, and session data. All MCPCat debug output goes to 
~/mcpcat.log
(never stdout/stderr, so STDIO transport is preserved).
MCPCat是针对MCP服务器的一行代码分析集成工具。调用
mcpcat.track(server, projectId)
即可捕获工具使用模式、用户意图和会话数据。所有MCPCat调试输出都会写入
~/mcpcat.log
（绝不会输出到stdout/stderr，因此STDIO传输得以保留）。

When to Use

适用场景

  • User wants to add analytics or usage tracking to their MCP server
  • User mentions "mcpcat", "MCPCat", or MCP server observability
  • User wants to understand how their MCP tools are being used
  • 用户希望为其MCP服务器添加分析或使用追踪功能
  • 用户提及“mcpcat”、“MCPCat”或MCP服务器可观测性
  • 用户希望了解其MCP工具的使用情况

Quick Reference

快速参考

ItemValue
Package
mcpcat
Import
import * as mcpcat from "mcpcat"
Core call
mcpcat.track(server, projectId)
Peer dep
@modelcontextprotocol/sdk >= 1.11
MCPCat log file
~/mcpcat.log
Project ID env var
MCPCAT_PROJECT_ID
Debug env var
MCPCAT_DEBUG_MODE
DefaultsAll features enabled (context injection, tracing, report-missing tool)
项目值
包
mcpcat
导入方式
import * as mcpcat from "mcpcat"
核心调用
mcpcat.track(server, projectId)
对等依赖
@modelcontextprotocol/sdk >= 1.11
MCPCat日志文件
~/mcpcat.log
项目ID环境变量
MCPCAT_PROJECT_ID
调试环境变量
MCPCAT_DEBUG_MODE
默认配置所有功能启用（上下文注入、追踪、缺失工具报告）

Implementation Checklist

实施检查清单

Follow these steps in order. Do NOT skip or reorder.
请按顺序执行以下步骤，请勿跳过或调整顺序。

0. Get the MCPCat project ID

0. 获取MCPCat项目ID

If the user did not provide a MCPCat project ID (a string like 
"proj_abc123xyz"
from mcpcat.io), ASK them for it before proceeding. Say something like:
"To set up MCPCat, I'll need your project ID from mcpcat.io. It looks like 
proj_abc123xyz
. Do you have one? You can create a free account at https://mcpcat.io to get one."
  • If they provide one: hardcode it as the default in the env var fallback, e.g. 
    process.env.MCPCAT_PROJECT_ID ?? "proj_their_id"
  • Do NOT skip this step or assume a project ID
如果用户未提供MCPCat项目ID（格式为
"proj_abc123xyz"
，来自mcpcat.io），请先向用户索要该ID再继续。可以这样说：
"要设置MCPCat，我需要您来自mcpcat.io的项目ID，格式类似
proj_abc123xyz
。您有这个ID吗？您可以在https://mcpcat.io创建免费账户来获取。"
  • 如果用户提供了ID：将其作为环境变量回退的默认值硬编码，例如
    process.env.MCPCAT_PROJECT_ID ?? "proj_their_id"
  • 请勿跳过此步骤或默认项目ID存在

1. Read the user's existing MCP server code

1. 阅读用户现有MCP服务器代码

Before making ANY changes, read the server file(s) and identify these three landmarks:
  • Server creation: 
    new McpServer(...)
    (high-level) or 
    new Server(...)
    (low-level)
  • Tool registrations: 
    server.registerTool(...)
    , 
    server.tool(...)
    , or 
    server.setRequestHandler(CallToolRequestSchema, ...)
  • Transport connection: 
    server.connect(transport)
    — usually inside an async 
    main()
    function
在进行任何修改之前，先阅读服务器文件并确定以下三个关键部分：
  • 服务器创建：
    new McpServer(...)
    （高层级）或
    new Server(...)
    （低层级）
  • 工具注册：
    server.registerTool(...)
    、
    server.tool(...)
    或
    server.setRequestHandler(CallToolRequestSchema, ...)
  • 传输连接：
    server.connect(transport)
    —— 通常位于异步
    main()
    函数内

2. Check peer dependency

2. 检查对等依赖

Look at 
package.json
and verify 
@modelcontextprotocol/sdk
version is 
>= 1.11
. If older, tell the user they must upgrade first.
查看
package.json
并验证
@modelcontextprotocol/sdk
版本是否
>= 1.11
。如果版本较低，请告知用户必须先升级。

3. Install the mcpcat package

3. 安装mcpcat包

Detect the package manager and install:
IndicatorCommand
pnpm-lock.yaml
pnpm add mcpcat
yarn.lock
yarn add mcpcat
bun.lockb
or 
bun.lock
bun add mcpcat
package-lock.json
npm install mcpcat
OtherwiseCheck the project's README and other 
.md
files for dependency management instructions, then install accordingly
检测包管理器并执行安装：
标识文件命令
pnpm-lock.yaml
pnpm add mcpcat
yarn.lock
yarn add mcpcat
bun.lockb
或 
bun.lock
bun add mcpcat
package-lock.json
npm install mcpcat
其他情况查看项目README及其他
.md
文件中的依赖管理说明，然后按说明安装

4. Add the import

4. 添加导入语句

Add near the top of the server file, alongside existing MCP SDK imports:
typescript
import * as mcpcat from "mcpcat";
Use the namespace import (
import * as mcpcat
), not named import (
import { track }
).
在服务器文件顶部靠近现有MCP SDK导入的位置添加：
typescript
import * as mcpcat from "mcpcat";
请使用命名空间导入（
import * as mcpcat
），而非命名导入（
import { track }
）。

5. Add the track() call

5. 添加track()调用

CRITICAL: The 
track()
function signature is:
typescript
mcpcat.track(server, projectId, options?)
  • 1st arg: The MCP server instance (both 
    McpServer
    and 
    Server
    work)
  • 2nd arg: Project ID string (e.g. 
    "proj_abc123xyz"
    )
  • 3rd arg: Options object (optional — all defaults are good, do NOT pass unless customizing)
WRONG: 
track(server, { projectId })
— this passes an options object as the 2nd arg. RIGHT: 
track(server, projectId)
— projectId is the 2nd positional argument.
Placement: Insert AFTER server creation and BEFORE 
server.connect(transport)
. Place it at the module level alongside tool registrations, NOT inside the async 
main()
function.
Always call track() with the project ID from the env var, falling back to the user's hardcoded ID:
typescript
mcpcat.track(server, process.env.MCPCAT_PROJECT_ID ?? "proj_their_id");
关键注意：
track()
函数签名为：
typescript
mcpcat.track(server, projectId, options?)
  • 第一个参数：MCP服务器实例（
    McpServer
    和
    Server
    均可）
  • 第二个参数：项目ID 字符串（例如
    "proj_abc123xyz"
    ）
  • 第三个参数：选项对象（可选——默认配置已足够，除非需要自定义否则请勿传递）
错误写法：
track(server, { projectId })
—— 将选项对象作为第二个参数传递 正确写法：
track(server, projectId)
—— projectId是第二个位置参数
放置位置：在服务器创建之后、
server.connect(transport)
之前插入。将其放在模块级别与工具注册代码一起，而非异步
main()
函数内部。
务必调用track()，使用环境变量中的项目ID，回退到用户提供的硬编码ID：
typescript
mcpcat.track(server, process.env.MCPCAT_PROJECT_ID ?? "proj_abc123xyz");

6. Add debug logging

6. 添加调试日志

MCPCat writes all its internal debug output to 
~/mcpcat.log
. Add a single stderr line (controlled by env var) so the user knows tracking is active:
typescript
if (process.env.MCPCAT_DEBUG_MODE) {
  console.error("[mcpcat] Analytics enabled. Debug log: ~/mcpcat.log");
}
Use 
console.error
, NEVER 
console.log
— stdout is the MCP protocol channel for STDIO transport.
Keep it to this single line. Do NOT create a debug utility function or add multiple debug log points.
MCPC会将所有内部调试输出写入
~/mcpcat.log
。添加一行stderr输出（由环境变量控制），让用户知晓追踪已激活：
typescript
if (process.env.MCPCAT_DEBUG_MODE) {
  console.error("[mcpcat] Analytics enabled. Debug log: ~/mcpcat.log");
}
请使用
console.error
，切勿使用
console.log
——stdout是MCP协议的STDIO传输通道。
仅保留这一行代码，请勿创建调试工具函数或添加多个调试日志点。

7. Verify

7. 验证

After making changes, confirm:
  • Server still starts and responds to tool calls
  • ~/mcpcat.log
    exists and contains initialization entries
  • No MCPCat output appears on stdout
修改完成后，请确认：
  • 服务器仍能正常启动并响应工具调用
  • ~/mcpcat.log
    已存在且包含初始化条目
  • 没有MCPCat输出出现在stdout中

Before and After

修改前后对比

BEFORE

修改前

typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.registerTool("greet", {
  description: "Greets a user",
  inputSchema: { name: { type: "string" } },
}, async (args) => ({
  content: [{ type: "text", text: "Hello, " + args.name + "!" }],
}));

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);
typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.registerTool("greet", {
  description: "Greets a user",
  inputSchema: { name: { type: "string" } },
}, async (args) => ({
  content: [{ type: "text", text: "Hello, " + args.name + "!" }],
}));

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

AFTER

修改后

typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import * as mcpcat from "mcpcat";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.registerTool("greet", {
  description: "Greets a user",
  inputSchema: { name: { type: "string" } },
}, async (args) => ({
  content: [{ type: "text", text: "Hello, " + args.name + "!" }],
}));

mcpcat.track(server, process.env.MCPCAT_PROJECT_ID ?? "proj_abc123xyz");

if (process.env.MCPCAT_DEBUG_MODE) {
  console.error("[mcpcat] Analytics enabled. Debug log: ~/mcpcat.log");
}

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);
Changes: one import, one 
track()
call, one debug log block.
typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import * as mcpcat from "mcpcat";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.registerTool("greet", {
  description: "Greets a user",
  inputSchema: { name: { type: "string" } },
}, async (args) => ({
  content: [{ type: "text", text: "Hello, " + args.name + "!" }],
}));

mcpcat.track(server, process.env.MCPCAT_PROJECT_ID ?? "proj_abc123xyz");

if (process.env.MCPCAT_DEBUG_MODE) {
  console.error("[mcpcat] Analytics enabled. Debug log: ~/mcpcat.log");
}

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);
修改内容：新增一个导入语句、一个
track()
调用、一个调试日志块。

Low-Level Server Pattern

低层级服务器模式

For servers using the 
Server
class directly:
typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import * as mcpcat from "mcpcat";

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// ... setRequestHandler calls ...

mcpcat.track(server, process.env.MCPCAT_PROJECT_ID ?? "proj_abc123xyz");

if (process.env.MCPCAT_DEBUG_MODE) {
  console.error("[mcpcat] Analytics enabled. Debug log: ~/mcpcat.log");
}

// Then connect transport as usual
对于直接使用
Server
类的服务器：
typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import * as mcpcat from "mcpcat";

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// ... setRequestHandler 调用 ...

mcpcat.track(server, process.env.MCPCAT_PROJECT_ID ?? "proj_abc123xyz");

if (process.env.MCPCAT_DEBUG_MODE) {
  console.error("[mcpcat] Analytics enabled. Debug log: ~/mcpcat.log");
}

// 然后按常规方式连接传输通道

Common Mistakes

常见错误

MistakeWhy it failsFix
track(server, { projectId })
Options object passed as 2nd arg instead of projectId string
track(server, projectId)
— projectId is the 2nd positional arg
if (projectId) { track(...) }
Skips tracking if env var is unset, defeating the hardcoded fallbackAlways call 
track(server, process.env.MCPCAT_PROJECT_ID ?? "proj_abc123xyz")
track()
after 
server.connect()
Transport starts before MCPCat intercepts handlersMove 
track()
before 
connect()
track()
called twice		MCPCat detects and skips, but indicates logic errorCall 
track()
exactly once per server
console.log
for debug output		Breaks STDIO transport (stdout is the MCP channel)Use 
console.error
Creating a debugLog utilityOver-engineers a one-linerSingle 
if (process.env.MCPCAT_DEBUG_MODE) console.error(...)
Expecting console output from MCPCatMCPCat logs to file, not consoleCheck 
~/mcpcat.log
@modelcontextprotocol/sdk
< 1.11		MCPCat requires >= 1.11Upgrade: 
npm install @modelcontextprotocol/sdk@latest
错误做法失败原因修复方案
track(server, { projectId })
将选项对象作为第二个参数传递，而非projectId字符串
track(server, projectId)
—— projectId是第二个位置参数
if (projectId) { track(...) }
如果环境变量未设置则跳过追踪，导致硬编码回退失效务必调用
track(server, process.env.MCPCAT_PROJECT_ID ?? "proj_abc123xyz")
在
server.connect()
之后调用
track()
传输通道在MCPCat拦截处理程序之前启动将
track()
移至
connect()
之前
调用两次
track()
MCPCat会检测到并跳过，但表明存在逻辑错误每个服务器仅调用一次
track()
使用
console.log
输出调试信息		破坏STDIO传输（stdout是MCP通道）使用
console.error
创建debugLog工具函数对单行代码过度设计仅保留
if (process.env.MCPCAT_DEBUG_MODE) console.error(...)
这一行
期望从MCPCat获取控制台输出MCPCat日志写入文件而非控制台查看
~/mcpcat.log
@modelcontextprotocol/sdk
版本 < 1.11		MCPCat要求版本 >= 1.11升级：
npm install @modelcontextprotocol/sdk@latest