MCP三原语开发：从Tool到npm发布全实战

graph TB
    subgraph "MCP三原语"
        T["Tool<br/>工具调用<br/>执行动作、产生副作用"]
        R["Resource<br/>数据暴露<br/>提供只读上下文数据"]
        P["Prompt<br/>提示词模板<br/>预设交互模式"]
    end

    T --> |"查询数据库"| T1["返回结构化结果"]
    T --> |"调用API"| T2["产生副作用"]
    T --> |"文件操作"| T3["读写变更"]

    R --> |"代码文件"| R1["实时文件内容"]
    R --> |"配置数据"| R2["应用状态"]
    R --> |"文档"| R3["知识库"]

    P --> |"代码审查"| P1["预设审查清单"]
    P --> |"调试助手"| P2["诊断流程模板"]
    P --> |"翻译"| P3["多语言格式模板"]

    style T fill:#4A90D9,color:#fff
    style R fill:#50C878,color:#fff
    style P fill:#FF6B6B,color:#fff

mkdir mcp-project-server && cd mcp-project-server
npm init -y

{
  "name": "mcp-project-server",
  "version": "1.0.0",
  "description": "A project management MCP server with Tools, Resources, and Prompts",
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "mcp-project-server": "dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "npx tsx src/index.ts",
    "inspect": "npx @modelcontextprotocol/inspector npx tsx src/index.ts",
    "prepublishOnly": "npm run build"
  },
  "files": ["dist"]
}

npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}

mcp-project-server/
├── src/
│   ├── index.ts          # 入口：服务器组装与启动
│   ├── tools/            # Tool定义
│   │   └── project.ts
│   ├── resources/        # Resource定义
│   │   └── project.ts
│   ├── prompts/          # Prompt定义
│   │   └── review.ts
│   └── store/            # 内存数据存储
│       └── projects.ts
├── tsconfig.json
├── package.json
└── .gitignore

// src/store/projects.ts

export interface Project {
  id: string;
  name: string;
  status: "active" | "completed" | "paused";
  description: string;
  tasks: Task[];
  createdAt: string;
}

export interface Task {
  id: string;
  title: string;
  done: boolean;
  assignee?: string;
}

// 内存数据存储
const projects: Map<string, Project> = new Map();

// 初始化示例数据
projects.set("proj-001", {
  id: "proj-001",
  name: "MCP Server开发",
  status: "active",
  description: "构建一个包含Tool、Resource、Prompt的完整MCP服务器",
  tasks: [
    { id: "t-1", title: "设计三原语API", done: true, assignee: "Alice" },
    { id: "t-2", title: "实现Tool处理器", done: true, assignee: "Bob" },
    { id: "t-3", title: "实现Resource处理器", done: false, assignee: "Alice" },
    { id: "t-4", title: "编写Prompt模板", done: false, assignee: "Charlie" },
  ],
  createdAt: "2026-05-20T10:00:00Z",
});

export function getAllProjects(): Project[] {
  return Array.from(projects.values());
}

export function getProject(id: string): Project | undefined {
  return projects.get(id);
}

export function createProject(
  name: string,
  description: string
): Project {
  const id = `proj-${String(projects.size + 1).padStart(3, "0")}`;
  const project: Project = {
    id,
    name,
    status: "active",
    description,
    tasks: [],
    createdAt: new Date().toISOString(),
  };
  projects.set(id, project);
  return project;
}

export function addTask(
  projectId: string,
  title: string,
  assignee?: string
): Project | null {
  const project = projects.get(projectId);
  if (!project) return null;
  const taskId = `t-${project.tasks.length + 1}`;
  project.tasks.push({ id: taskId, title, done: false, assignee });
  return project;
}

export function completeTask(
  projectId: string,
  taskId: string
): Project | null {
  const project = projects.get(projectId);
  if (!project) return null;
  const task = project.tasks.find((t) => t.id === taskId);
  if (!task) return null;
  task.done = true;
  return project;
}

// src/tools/project.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import {
  getAllProjects,
  getProject,
  createProject,
  addTask,
  completeTask,
} from "../store/projects.js";

export function registerProjectTools(server: McpServer): void {
  // Tool 1: 列出所有项目
  server.tool(
    "list_projects",
    "列出所有项目及其状态概览",
    {},
    async () => {
      const projects = getAllProjects();
      const summary = projects.map((p) => ({
        id: p.id,
        name: p.name,
        status: p.status,
        tasks: `${p.tasks.filter((t) => t.done).length}/${p.tasks.length} 已完成`,
      }));
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(summary, null, 2),
          },
        ],
      };
    }
  );

  // Tool 2: 查看项目详情
  server.tool(
    "get_project",
    "获取指定项目的完整详情，包含所有任务",
    {
      projectId: z
        .string()
        .describe("项目ID，格式为 proj-XXX"),
    },
    async ({ projectId }) => {
      const project = getProject(projectId);
      if (!project) {
        return {
          content: [
            {
              type: "text",
              text: `错误：未找到项目 ${projectId}`,
            },
          ],
          isError: true,
        };
      }
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(project, null, 2),
          },
        ],
      };
    }
  );

  // Tool 3: 创建新项目
  server.tool(
    "create_project",
    "创建一个新项目",
    {
      name: z.string().min(1).describe("项目名称"),
      description: z.string().describe("项目描述"),
    },
    async ({ name, description }) => {
      const project = createProject(name, description);
      return {
        content: [
          {
            type: "text",
            text: `项目已创建：${project.id} - ${project.name}`,
          },
        ],
      };
    }
  );

  // Tool 4: 添加任务
  server.tool(
    "add_task",
    "向指定项目添加新任务",
    {
      projectId: z.string().describe("目标项目ID"),
      title: z.string().min(1).describe("任务标题"),
      assignee: z.string().optional().describe("负责人（可选）"),
    },
    async ({ projectId, title, assignee }) => {
      const project = addTask(projectId, title, assignee);
      if (!project) {
        return {
          content: [
            {
              type: "text",
              text: `错误：未找到项目 ${projectId}`,
            },
          ],
          isError: true,
        };
      }
      const newTask = project.tasks[project.tasks.length - 1];
      return {
        content: [
          {
            type: "text",
            text: `任务已添加到 ${project.name}：[${newTask.id}] ${newTask.title}${assignee ? ` → ${assignee}` : ""}`,
          },
        ],
      };
    }
  );

  // Tool 5: 完成任务
  server.tool(
    "complete_task",
    "将指定任务标记为已完成",
    {
      projectId: z.string().describe("项目ID"),
      taskId: z.string().describe("任务ID"),
    },
    async ({ projectId, taskId }) => {
      const project = completeTask(projectId, taskId);
      if (!project) {
        return {
          content: [
            {
              type: "text",
              text: `错误：未找到项目 ${projectId} 或任务 ${taskId}`,
            },
          ],
          isError: true,
        };
      }
      const doneCount = project.tasks.filter((t) => t.done).length;
      return {
        content: [
          {
            type: "text",
            text: `任务 ${taskId} 已完成！进度：${doneCount}/${project.tasks.length}`,
          },
        ],
      };
    }
  );
}

// src/resources/project.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { getAllProjects, getProject } from "../store/projects.js";

export function registerProjectResources(server: McpServer): void {
  // Resource 1: 静态URI — 项目列表摘要
  server.resource(
    "projects-summary",
    "projects://summary",
    async (uri) => {
      const projects = getAllProjects();
      const lines = projects.map(
        (p) =>
          `- [${p.status.toUpperCase()}] ${p.name} (${p.id}): ` +
          `${p.tasks.filter((t) => t.done).length}/${p.tasks.length} tasks`
      );
      return {
        contents: [
          {
            uri: uri.href,
            mimeType: "text/plain",
            text: `# 项目概览 (${projects.length}个项目)\n\n${lines.join("\n")}`,
          },
        ],
      };
    }
  );

  // Resource 2: 动态URI模板 — 单个项目详情
  server.resource(
    "project-detail",
    new URL("projects://{projectId}/detail"),
    async (uri, { projectId }) => {
      const project = getProject(projectId);
      if (!project) {
        return {
          contents: [
            {
              uri: uri.href,
              mimeType: "text/plain",
              text: `未找到项目：${projectId}`,
            },
          ],
        };
      }

      const taskList = project.tasks
        .map(
          (t) =>
            `  [${t.done ? "x" : " "}] ${t.id}: ${t.title}` +
            (t.assignee ? ` @${t.assignee}` : "")
        )
        .join("\n");

      return {
        contents: [
          {
            uri: uri.href,
            mimeType: "text/markdown",
            text:
              `# ${project.name}\n\n` +
              `**状态**: ${project.status}\n` +
              `**创建时间**: ${project.createdAt}\n\n` +
              `## 描述\n${project.description}\n\n` +
              `## 任务清单\n${taskList}`,
          },
        ],
      };
    }
  );

  // Resource 3: 静态URI — 团队工作量统计
  server.resource(
    "team-workload",
    "projects://team-workload",
    async (uri) => {
      const projects = getAllProjects();
      const workload: Record<string, { total: number; done: number }> = {};

      for (const p of projects) {
        for (const t of p.tasks) {
          if (t.assignee) {
            if (!workload[t.assignee]) {
              workload[t.assignee] = { total: 0, done: 0 };
            }
            workload[t.assignee].total++;
            if (t.done) workload[t.assignee].done++;
          }
        }
      }

      const lines = Object.entries(workload).map(
        ([name, w]) => `- ${name}: ${w.done}/${w.total} 完成`
      );

      return {
        contents: [
          {
            uri: uri.href,
            mimeType: "text/plain",
            text: `# 团队工作量\n\n${lines.join("\n")}`,
          },
        ],
      };
    }
  );
}

graph LR
    subgraph "Resource（数据暴露）"
        direction TB
        R1["AI按需拉取"]
        R2["只读，无副作用"]
        R3["URI定位数据"]
        R4["返回内容供上下文使用"]
        R1 --> R2 --> R3 --> R4
    end

    subgraph "Tool（工具调用）"
        direction TB
        T1["AI主动调用"]
        T2["可有副作用"]
        T3["参数化输入"]
        T4["返回结果供下一步决策"]
        T1 --> T2 --> T3 --> T4
    end

// src/prompts/review.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { getProject } from "../store/projects.js";

export function registerProjectPrompts(server: McpServer): void {
  // Prompt 1: 项目状态报告生成
  server.prompt(
    "status-report",
    "生成指定项目的状态报告模板",
    {
      projectId: z.string().describe("项目ID"),
      format: z
        .enum(["markdown", "text"])
        .optional()
        .describe("输出格式，默认markdown"),
    },
    async ({ projectId, format }) => {
      const project = getProject(projectId);
      const projectName = project?.name ?? "未知项目";
      const useMarkdown = format !== "text";

      const instruction = useMarkdown
        ? `请为项目「${projectName}」生成一份Markdown格式的状态报告，包含以下章节：

## 项目概览
- 项目名称：${projectName}
- 当前状态：${project?.status ?? "未知"}
- 报告日期：${new Date().toISOString().split("T")[0]}

## 进度摘要
请分析当前任务完成情况并给出百分比和趋势判断。

## 风险与阻塞
请识别未完成任务中的潜在风险点。

## 下一步行动
请为每个未完成任务建议具体的下一步操作。

## 团队分配
请分析团队成员的工作负载是否均衡。`
        : `请为项目「${projectName}」生成一份纯文本状态报告，包含：项目名称、当前状态、进度百分比、风险点、下一步行动。保持简洁，每项不超过两行。`;

      return {
        messages: [
          {
            role: "user",
            content: { type: "text", text: instruction },
          },
        ],
      };
    }
  );

  // Prompt 2: 任务分派指令
  server.prompt(
    "assign-tasks",
    "生成任务分派建议",
    {
      projectId: z.string().describe("项目ID"),
      teamMembers: z
        .string()
        .describe("团队成员，逗号分隔，如：Alice,Bob,Charlie"),
    },
    async ({ projectId, teamMembers }) => {
      const project = getProject(projectId);
      const pendingTasks = project?.tasks.filter((t) => !t.done) ?? [];
      const members = teamMembers.split(",").map((m) => m.trim());

      const taskList = pendingTasks
        .map((t) => `- [ ] ${t.title}${t.assignee ? ` (当前: @${t.assignee})` : ""}`)
        .join("\n");

      return {
        messages: [
          {
            role: "user",
            content: {
              type: "text",
              text:
                `请为以下未完成任务做最优分派建议。\n\n` +
                `## 团队成员\n${members.map((m) => `- ${m}`).join("\n")}\n\n` +
                `## 待分派任务\n${taskList}\n\n` +
                `请考虑以下原则：\n` +
                `1. 负载均衡：尽量平均分配\n` +
                `2. 专业对口：根据任务内容匹配最合适的成员\n` +
                `3. 依赖关系：有前后依赖的任务尽量分给同一人\n` +
                `4. 输出格式：表格，列为 [任务 | 建议负责人 | 理由]`,
            },
          },
        ],
      };
    }
  );

  // Prompt 3: 每日站会模板
  server.prompt(
    "daily-standup",
    "生成每日站会报告模板",
    {
      projectId: z.string().describe("项目ID"),
      reporter: z.string().describe("报告人姓名"),
    },
    async ({ projectId, reporter }) => {
      const project = getProject(projectId);
      const myTasks = project?.tasks.filter((t) => t.assignee === reporter) ?? [];
      const doneTasks = myTasks.filter((t) => t.done);
      const pendingTasks = myTasks.filter((t) => !t.done);

      return {
        messages: [
          {
            role: "user",
            content: {
              type: "text",
              text:
                `请帮 ${reporter} 生成「${project?.name ?? projectId}」的每日站会报告。\n\n` +
                `## 昨天完成\n${doneTasks.length > 0 ? doneTasks.map((t) => `- ✅ ${t.title}`).join("\n") : "- 无"}\n\n` +
                `## 今天计划\n${pendingTasks.length > 0 ? pendingTasks.map((t) => `- 📋 ${t.title}`).join("\n") : "- 无待办"}\n\n` +
                `## 阻塞/风险\n请根据任务状态分析是否存在阻塞点，并给出建议。\n\n` +
                `请用简洁的语言整理，适合在3分钟内口头汇报。`,
            },
          },
        ],
      };
    }
  );
}

#!/usr/bin/env node

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { registerProjectTools } from "./tools/project.js";
import { registerProjectResources } from "./resources/project.js";
import { registerProjectPrompts } from "./prompts/review.js";

async function main() {
  // 创建MCP服务器实例
  const server = new McpServer({
    name: "mcp-project-server",
    version: "1.0.0",
    description: "项目管理MCP服务器 — 支持Tool、Resource、Prompt三原语",
  });

  // 注册三原语
  registerProjectTools(server);
  registerProjectResources(server);
  registerProjectPrompts(server);

  // 使用Stdio传输层启动
  const transport = new StdioServerTransport();
  await server.connect(transport);

  // 注意：Stdio模式下不要用console.log
  // 所有输出通过MCP协议传输，console.log会污染通信管道
}

main().catch((error) => {
  // 错误输出用stderr，不会污染MCP通信
  process.stderr.write(`Fatal error: ${error}\n`);
  process.exit(1);
});

npx tsc
# 无错误输出则编译成功

# 开发模式：直接用tsx运行源码
claude mcp add project-server -- npx tsx /path/to/mcp-project-server/src/index.ts

# 发布后：用npx运行npm包
claude mcp add project-server -- npx -y mcp-project-server

{
  "mcpServers": {
    "project-server": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "type": "stdio"
    }
  }
}

{
  "mcpServers": {
    "project-server": {
      "command": "npx",
      "args": ["-y", "mcp-project-server"],
      "type": "stdio"
    }
  }
}

> /mcp

● project-server (stdio)
  Tools: list_projects, get_project, create_project, add_task, complete_task
  Resources: projects-summary, project-detail, team-workload
  Prompts: status-report, assign-tasks, daily-standup

# 方式一：通过package.json的script
npm run inspect

# 方式二：直接运行
npx @modelcontextprotocol/inspector npx tsx src/index.ts

flowchart TD
    A["启动Inspector"] --> B["连接MCP服务器"]
    B --> C["查看Capabilities"]
    C --> D{选择原语}
    D --> |"Tool"| E["列出所有Tools"]
    D --> |"Resource"| F["列出所有Resources"]
    D --> |"Prompt"| G["列出所有Prompts"]
    E --> H["选择Tool → 填参数 → 执行"]
    F --> I["选择Resource → 读取内容"]
    G --> J["选择Prompt → 填参数 → 生成"]
    H --> K["查看返回结果"]
    I --> K
    J --> K
    K --> L["检查JSON格式是否正确"]

{
  "name": "mcp-project-server",
  "version": "1.0.0",
  "description": "A project management MCP server with Tools, Resources, and Prompts",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "bin": {
    "mcp-project-server": "dist/index.js"
  },
  "keywords": ["mcp", "model-context-protocol", "claude", "ai-tools"],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourname/mcp-project-server"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

src/
tsconfig.json
node_modules/
.git/

# 编译TypeScript
npx tsc

# 验证编译产物
ls -la dist/
# 应看到 index.js, tools/project.js, resources/project.js, prompts/review.js 等

# 本地测试运行
node dist/index.js
# 应无错误输出（服务器在等待stdin输入）

# 登录npm（首次）
npm login

# 发布
npm publish

# 如果包名已被占用，使用scope
npm publish --access public
# 包名需改为 @yourname/mcp-project-server

# 全局测试
npx -y mcp-project-server

# 在Claude Code中配置
claude mcp add project-server -- npx -y mcp-project-server

# 验证
claude
> /mcp

# 修改代码后
npx tsc                           # 重新编译
npm version patch                 # 1.0.0 → 1.0.1
npm publish                       # 发布新版本

# Claude Code用户无需任何操作
# npx -y 会自动拉取最新版本

用户：帮我看看当前有哪些项目

Claude：我来查看项目列表。
[调用 list_projects Tool]

当前有2个项目：

1. **MCP Server开发** (proj-001)
   - 状态：active
   - 进度：2/4 已完成

2. **AI搜索优化** (proj-002)
   - 状态：active
   - 进度：0/0 已完成

---

用户：给MCP Server项目加一个任务"编写单元测试"，分配给Bob

Claude：
[调用 add_task Tool，参数：{ projectId: "proj-001", title: "编写单元测试", assignee: "Bob" }]

任务已添加到 MCP Server开发：[t-5] 编写单元测试 → Bob

---

用户：生成Alice的每日站会报告

Claude：
[调用 daily-standup Prompt，参数：{ projectId: "proj-001", reporter: "Alice" }]

根据Prompt模板生成的站会报告：

## Alice 每日站会 — MCP Server开发

### 昨天完成
- ✅ 设计三原语API
- ✅ 实现Resource处理器（待确认，task t-3可能未完成）

### 今天计划
- 📋 实现Resource处理器
- 📋 编写Prompt模板

### 阻塞/风险
t-3（实现Resource处理器）已持续较长时间，建议确认是否有技术难点。

---

用户：帮我读取项目概览数据

Claude：
[读取 projects://summary Resource]

# 项目概览 (2个项目)

- [ACTIVE] MCP Server开发 (proj-001): 2/4 tasks
- [ACTIVE] AI搜索优化 (proj-002): 0/0 tasks

graph TB
    subgraph "Claude Code"
        CC["Claude Code CLI"]
        MCP["MCP Client"]
    end

    subgraph "mcp-project-server"
        direction TB
        ENTRY["index.ts<br/>服务器入口"]

        subgraph "三原语注册"
            TOOLS["Tools<br/>5个工具"]
            RES["Resources<br/>3个数据端点"]
            PROMPTS["Prompts<br/>3个模板"]
        end

        STORE["内存数据存储<br/>projects Map"]
    end

    CC -->|"stdin/stdout<br/>Stdio传输"| MCP
    MCP -->|"MCP协议"| ENTRY
    ENTRY --> TOOLS
    ENTRY --> RES
    ENTRY --> PROMPTS
    TOOLS --> STORE
    RES --> STORE
    PROMPTS --> STORE

    subgraph "工具清单"
        T1["list_projects"]
        T2["get_project"]
        T3["create_project"]
        T4["add_task"]
        T5["complete_task"]
    end

    subgraph "数据端点"
        R1["projects://summary"]
        R2["projects://{id}/detail"]
        R3["projects://team-workload"]
    end

    subgraph "提示词模板"
        P1["status-report"]
        P2["assign-tasks"]
        P3["daily-standup"]
    end

    TOOLS -.-> T1 & T2 & T3 & T4 & T5
    RES -.-> R1 & R2 & R3
    PROMPTS -.-> P1 & P2 & P3

    style CC fill:#4A90D9,color:#fff
    style ENTRY fill:#FF9500,color:#fff
    style TOOLS fill:#50C878,color:#fff
    style RES fill:#9B59B6,color:#fff
    style PROMPTS fill:#E74C3C,color:#fff
    style STORE fill:#F39C12,color:#fff

# 好的描述：包含触发条件和行为
"列出所有项目及其状态概览，当用户询问项目情况时使用"

# 差的描述：模糊不清
"获取数据"

// 推荐：使用 isError 标记
if (!project) {
  return {
    content: [{ type: "text", text: `错误：项目 ${id} 不存在` }],
    isError: true,  // 让Claude知道这是错误，不是正常结果
  };
}

// 反模式：throw Error
// throw new Error("Project not found");
// 这会导致MCP协议错误，Claude无法理解具体原因

graph LR
    subgraph "Stdio（本地）"
        A["Claude Code"] -->|"stdin/stdout"| B["MCP Server进程"]
    end

    subgraph "Streamable HTTP（远程）"
        C["Claude Code"] -->|"HTTP POST"| D["MCP Server<br/>:3000"]
        E["Cursor"] -->|"HTTP POST"| D
        F["其他AI客户端"] -->|"HTTP POST"| D
    end

    style B fill:#50C878,color:#fff
    style D fill:#4A90D9,color:#fff

import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
import express from "express";

// ... 服务器创建代码相同 ...

const app = express();
app.use(express.json());

const transports: Map<string, StreamableHTTPServerTransport> = new Map();

app.post("/mcp", async (req, res) => {
  const sessionId = req.headers["mcp-session-id"] as string | undefined;
  let transport: StreamableHTTPServerTransport;

  if (sessionId && transports.has(sessionId)) {
    // 复用已有session
    transport = transports.get(sessionId)!;
  } else if (!sessionId && isInitializeRequest(req.body)) {
    // 新session
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
    });
    transports.set(transport.sessionId!, transport);
    await server.connect(transport);
  } else {
    res.status(400).json({ error: "Invalid request" });
    return;
  }

  await transport.handleRequest(req, res, req.body);
});

app.listen(3000, () => {
  process.stderr.write("MCP Server running on http://localhost:3000/mcp\n");
});

{
  "mcpServers": {
    "project-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}