> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magic-resume.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 内部细节

> @magic-resume/mcp 的内部接线 —— 入口、配置、与 Core API 的契约。

给打算改 MCP 包本身或 fork 一份的贡献者看。

## 目录

```
packages/mcp/
├── src/
│   ├── cli.ts           # `magic-resume` CLI 入口（config get/set/print/clear）
│   ├── server.ts        # MCP 服务器：工具注册、stdio 传输
│   ├── resume-tools.ts  # 上面那些工具的业务逻辑
│   ├── config.ts        # ~/.magic-resume/mcp.json 读写
│   └── http.ts          # 一个携带 PAT 的薄 axios 封装
├── test/                # node --test 套件
└── package.json         # type: "module", bin: magic-resume
```

CLI 和服务器共用 `config.ts` 与 `http.ts`。CLI 负责一次性的配置命令；MCP 服务器是 AI 工具拉起的进程。

## 入口

* **CLI：** `package.json` 里的 `bin: { "magic-resume": "./dist/cli.js" }`。子命令：`config set`、`config get`、`config print`、`config clear`，以及 `mcp`（启动服务器）。
* **MCP 服务器：** `magic-resume mcp` 启动 `server.ts`，注册工具，挂上 `StdioServerTransport`，常驻运行。

## 配置文件

`~/.magic-resume/mcp.json`：

```json theme={null}
{
  "apiUrl": "https://api.magic-resume.cn/api",
  "pat": "mr_pat_xxx"
}
```

`config.ts` 在第一次使用时懒加载。Windows 上路径是 `%USERPROFILE%\.magic-resume\mcp.json`。

<Warning>
  这个文件以明文存了 PAT。CLI 在 POSIX 系统上把权限设为 `0600`。如果你在 Windows 上贡献代码，不要放宽这个设置。
</Warning>

## 工具注册

`server.ts` 用 `@modelcontextprotocol/sdk` 注册每个工具，提供：

* 名字和描述
* 用 Zod 派生的输入 Schema（让模型拿到带类型的参数提示）
* 一个调用 `resume-tools.ts` 的 handler

工具总是返回结构化 JSON。错误以稳定错误码抛出 `McpError`，让 AI 工具能据此反应（如网络瞬断时重试，校验错时放弃）。

## Core API 契约

MCP 服务器是 Web 应用所用 NestJS Core API 的另一个客户端。相关接口：

| Endpoint            | Method | 鉴权  |
| ------------------- | ------ | --- |
| `/api/resumes/mine` | GET    | PAT |
| `/api/resumes/:id`  | GET    | PAT |
| `/api/resumes/:id`  | PATCH  | PAT |

`http.ts` 自动附上 `Authorization: Bearer <pat>`。和 Web 应用不同，**这里没有 Clerk** —— PAT 是 Core API 单独认识的一套鉴权方式。

## 构建与发布

```bash theme={null}
pnpm --filter @magic-resume/mcp build      # tsc → dist/
pnpm --filter @magic-resume/mcp test       # node --test test/*.test.mjs
pnpm --filter @magic-resume/mcp lint       # tsc --noEmit
```

发布由 `publishConfig.access = "public"` 控制，pnpm 在打包时会把 `workspace:*` 重写为真实 semver，这样发出去的 `package.json` 里 `@magic-resume/resume-schema` 和 `@magic-resume/resume-templates` 都有合法版本号。

## 加一个新工具

1. 把 handler 加到 `resume-tools.ts`。保持函数纯粹，并基于 patch。
2. 在 `server.ts` 里注册它，附上 Zod 输入 Schema 和简短描述。
3. 在 `test/` 里加 `node --test` 用例。
4. 如果新工具读取或修改了新字段，更新 [`get_resume_editing_guide`](/zh/mcp/tools#get_resume_editing_guide)，让模型知道怎么用。