内容
cvcp
MCP 服务器（stdio）用于同步您的 **CvLAC** （MinCiencias）个人资料与您的网站，使用 **TypeScript + Playwright**。
不会携带任何人数据：您的凭证、精选项目存放在，仓库忽略这些文件。适用于任何拥有AC 简历允许：
- 读取AC 数据（`vlac`）
-集（`read_portfolio`）
- 计算差异diff`）：缺失更新、相似和
- 按章节应用更改（`update_section`：` / `update `delete`）
-（`sync`，带有 `dry_run`写入时双重保证：**绝不未经确认创建重复项** （如果已有相似或相同项，则返回_confirmation` 而非写入 **始终报告失败，当 CvLAC 拒绝表单时。
> **负责任地使用**。这使用您的账户自动化了一个。请在应用前手动监督并检查每次 `dry_run`，不要无人监督地已验证内容、待和已知限制： **[ROADMAP.md](ROADMAP。
---
## 目录 [快速开始：安装和配置 MCP（Linux、Windows、macOS）](#快速和配置-mcp-linux-windows-macos)
- [)
- [ MCP 工具](#可-工具)
环境变量](#环境变量 [本地使用](#)
- [推荐流程)
- [构建](#测试和构建)
- [故障排除](#故障排除)
- [安全和最佳实践](#安全和最佳- [状态和路线和路线图)
---
## 快速开始：安装和配置 MCP（Linux、macOS）
安装和配置指南。按顺序执行每个步骤；都包含一个验证环境正确。
### 0 - 前置条件平台）
您Node.js 20**，**npm+** 和 **。
| 平台 | 如何安装 Node 20+ |
|---|---|
| **LinuxDebian/Ubuntu） | `curl -fsSL https://deb.nodesource.com/setup_20.x \| sudo -E bash - && sudo apt-get install -y nodejs git` **Linux** （版，推荐） | 安装 [nvm](https.com/nvm-sh/nvm) 然后执行 `nvm install 20 && nvm use 20` |
| **macOS** | `brew install node@20 git` （使用 [Homebrew](https://brew.sh)）或 nvm |
| **Windows** | `winget install OpenJS.NodeJS.LTS` 和 `winget install Git.Git` （或从.org](https://nodejs 下载安装程序）** （适用于zsh 或 PowerShellbash
node # 显示 v 或更高版本
npm # 显示 或更高版本
version
```
### 1 - 克隆**Linux / macOS zsh）：bash
cd ~/ # 或您喜欢的git clone https:///stivenson/c-mcp.git
cd cvlac-mcp
```
（PowerShell）：powershell
cd $HOME\dev # 如果目录先创建：mkdir $HOME\dev
git clonegithub.com/stivac-mcpcd cvlac-mcp
```
### 步骤 安装依赖并编译平台均适用：
npm install
```
**** 编译后的入口dist/index.js`。
```bash
/ macOS
ls dist/index.js
```
```powershell
# Windows（PowerShell）
Test-Path dist\index.js 应输出 True
```
### 步骤 3 - 安装 Playwright 浏览器
服务器使用无头 Chromium LAC。显（在任何操作系统上都稳健）：
```npx playwright install chromium
```
在 **Linux，如果缺少系统库，请
```bash
playwright install-deps # 在某些发行版 sudo
```
### 步骤 4 - 配置（`.env`复制模板并编辑值**Linux / macOS：**
```bash
env.example .env
```
**Windows（PowerShellpowershell
Copy-Item .env.example .env编辑 `.env` 以添加您的信息：
```bashLAC_NOMBRE=您的姓名
CV_CEDULA=号码
CVL您的密码
AC_SESSION_PATH=/path/.cvl.json
PORTF_URL=https://your.github.io
```
限制 `.env` 文件权限（Linux/macOS）：
```bash
chmod 600 .env
```
不同平台的 `CVLAC_SESSION_PATH` 示例：
- **Linux:** `/home/YOUR_USERNAME/.cvlac-session.json`
- **macOS:** `/Users/YOUR_USERNAME/.cvlac-session.json`
- **Windows:** `C:\\Users_USERNAME\\.c-session.json`
### 4b - 配置您的默认值（`ac.config.json
几个 CvLAC 表单需要您的作品集中没有的字段（城市、学时、语言）。请在这里一次性声明：
```bash
cp cvlac.config.example.json cvlac.config```json
{
"portfolioUrl": "https://your-username.github.io",
"ownerNamePattern": "您的姓名",
defaults": {
"municipio": { "Bogotá", "codigoDane": "11001" },
"institucionFallback": "Universidad Nacional de Colombia",
"horasSemanales": 1,
"idioma": "ES",
" "CO"
}
}
```
所有内容均为**如果缺少某个值，则该字段将留将带有警告** - 服务器不会为您的简历捏造数据。
### 步骤 4c - 维护项目、软件和事件（`data/portfolio-extra.json`）
这三个部分无法从作品集中读取需要只有 CvLAC 拥有的元数据（项目类型、DANE 代码、枚举代码）。请手动
```bash
cp data/portfolio-extra.example.json data/portfolio-extra.json
```
加载文件时进行验证；如果某个项目格式错误，服务器将报告并继续处理其他部分。
### 步骤 5 - 在 Cursor 中注册 MCP
服务器通过 **stdio** 运行，其实际入口点是 `dist/index.js`。将其添加到 Cursor 的 MCP。
`mcp.json` 文件位置：
- ** — Linux/macOS: `~/.cursor/m · Windows: `%USERPROFILE%\.cursor\mcp.json`
- **按项目** — `<project/mcp.json`
内容（调整 `args` 路径以适应您的系统）：
```json
{
"mcpServers": {
"cvlac-mcp": {
"command": "node",
": ["/home/YOUR_USERNAME/dev/cvlcp/dist/index.js"]
}
}
}
```
`args` 路径而异：
- **Linux:** `"/home/YOUR_USERNAME/dev/cvlac-mcp/dist/index.js"`
- **macOS:** `"/Users/YOUR_USERNAME/dev/cvlac-mcp/dist/index.js"`
- **Windows:** `"C:\\Users\\YOUR_USERNAME\\dev\\cvlac-mcp\\dist\\index.js"` （在 JSON 中使用双反斜杠）
> **将凭证仅保存在 `.env` 中。** 服务器从其自身目录加载，因此无需在 `mcp.json` 中重复 - 而该文件通常位于您的主目录中，权限不严格，或者在多台机器上同步。如果您仍然将它们放在 `env` 块中，它们将优先于 `.env`。
### 步骤 6 - 验证安装
1. **构建和测试** 成功：
```bash
npm run build
npm test
```
2. **启动服务器** （健康检查；保持运行直到 `Ctrl+C`）：
```bash
node
```
3. **在 Cursor 中启/重新加载，打开 MCP 设置，并cvlac-mcp` 显示为活动状态指示器）及其工具列表。
4. **** 从 Cursor 聊天中，按此顺序：
- `login` （应认证并保持 - `read_portfolio` （应返回数据）
- `diff` （应报告` / `upToDate`）
如果这三个响应没有错误，则 MCP 已正确安装和配置。
---
## 架构
```text
src/
.ts # 入口点（dotenv + stdio 传输）
├── server.ts # MCP 工具注册
├── types.ts # portfolio/CvLAC/diff/update 类型
├── diff.ts # 比较引擎（normalize + nameMatches）
├── browser/
│ ├── session.ts # 登录，持久会话，Playwright 上下文
│ └── navigation.ts # CvLAC 列表和表单 URL
├── tools/
│ ├── login.ts
│ ├── read-cvlac│ ├── read.ts
│ .ts
│ ├── update-section.ts # 按章节添加/更新/删除
│ ├── sync│ └── screenshot.ts
└── extractors ├── portfolio.ts
└── cvlac/
formacion.ts experiencia.ts cursos.ts reconocimientos.ts
proyectos.ts software.ts eventos.ts
```
---
## 可用的 MCP 工具
- `login`: 在 CvLAC 中认证并保持会话。
- `read_cvlac`: 从 CvLAC 读取一个或所有章节。
- `read_portfolio`: 获取并解析作品集。
- `diff`: 比较 CvLAC 与作品集并报告四类：`missing`、`toUpdate`、`similar`（与现有内容相似）和 `up。
- `update_section`: 应用逐项更改（`add`、`update`、`delete`）。返回 `status`、`warnings` 每个字段，如果检测到可能重复，则返回 `needs_confirmation` 候选项。`confirm_duplicate:true` 强制创建。
- `sync`: 执行差异 + 应用 `missing`toUpdate`（可选 `dry_run`）。` 永远不会自动应用。
- `screenshot`: 捕获当前状态屏幕截图。
- `inspect_form`: 检查 CvLAC URL 的实际字段 (`input/select/textarea`)。
支持的章节：
`form、`experiencia`、`cursos`、`recon、`proyectos`、`software`、`eventos`。
---
## 环境变量
在 `.env定义（参见 [步骤 4](#步骤-配置环境变量-env)）：
| |
|---|---|
| `CVLAC_N` | 您在 CvLAC 中登录的名称 |
| `CVLAC_CEDULA` | 身份证件号码 |
| `CVLAC_PASSWORD` | CvLAC 密码 |
| `CV_SESSION_PATH` | 保存 `storageState` 以重用会话的路径 |
| `PORTFOLIO_URL` | 要比较的作品集。也可以在 `cvlac.config.json` 中配置为 ` |
可选： 变量 | 描述---|---|
| `CVLAC_HEADLESS` | `false` 打开浏览器以查看其操作 |
| `CVLAC_LOG_LEVEL` | `debug `info` （默认）\| `warn`` \| `silent`。日志输出到 stderr |
| `CVLAC_LOG_FILE` | 除了 stderr 之外，还将每行追加到 |
| `CV_USER_AGENT` |浏览器的用户代理 |
| `CVLAC_CONFIG_PATH` | `cvlac.config.json` 的替代位置 |
| `CVLAC_PORTFOLIO_EXTRA_PATH` | `portfolio-extra.json` 的替代位置 |
---
## 本地使用
### 开发模式（无需编译）
```bash
npm run dev
```
### 本地生产模式（编译）
```bash
npm run build
npm start
```
---
## 推荐流程
1. `login`
2. 带有 `dry_run: true` 的 `3. 与人员审查报告：缺失、、**相似** 和已同步
4独解决相似问题 - 在现有基础上 `update`，或带有 `confirm_duplicate:true` 的 `add`
5. 应用其余部分：带有_run` 的 `sync`，或逐项审查 `warnings` 的 `update_section`
6. 使用 `read_cvlac` 或 `screenshot`修改的章节
如果您使用 Claude Code的 [workspace](https://github.com/stivenson/cvlac-workspace) 中的 `cvl` 技能封装了此流程。
###
```mermaid
flowchart LR
portfolio["read_portfolio"] --> diffEngine
cvlacRead["read_cvlac"] --> diffEngine["diff"]
diffEngine --> syncTool["sync (dry_run / apply)"]
syncTool -->["update_section add/update/delete"]
```
---
## 测试和构建
```bash
npm test # 完整的测试套件：无网络，无凭证，无 CvLAC
npm run build
```
测试涵盖了提取器（针对匿名 HTML fixtures）、差异引擎、模式、配置加载、日志中机以及 `sync` 报告。fixtures 中的数据故意使用虚构数据：如果您捕获了新的 HTML，请在提交前进行匿名处理。
可用命令```bash
npm run dev
npm run test:watch
npm start
```
---
##
### MCP 使用
- 在更改 `src/` 后，请确保运行 `npm run build`。
- 客户端 MCP 执行 `dist/index，而不是 `src/index.ts`。
### Cursor 中未出现 `cvlac-mcp`
`mcp.json` 中的绝对路径（步骤 5）并确保 `dist/index.js` 存在。
- 在 Windows 上，在 JSON 中使用双 (`\\`)。
- 编辑 `mcp.json` 后重启/重新加载 Cursor。
### Playwright 初始化浏览器时出错
- 运行 `npx playwright install chromium`。
- 在 Linux 上，使用 `npx playwright install-deps chromium` 添加系统依赖。
### 意外的登录重定向
- 会话可能已过期。再次运行 `login`。
- 验证 `.env` （或 `mcp.json` 中的`）是否凭证。
###未应用于表单
- CvLAC 的某些字段是 `readonly` 的，并通过 JS 设置。
- 使用 `inspect_form` 和 `screenshot` 验证实际字段名称。
- 将 `docs/cvlac-findings.md视为事实来源。
### `diff` 中的假缺失
- `nameMatches()` 规范化重音和后缀（例如 `(Platzi)`、` - Approved ...`）。
iencia` 故意排除在自动差异之外。
---
## 安全和最佳实践
- 不凭证。
- 不提交 `.env` 或会话/截图文件。
- 在 `dry_run`运行 `sync`。
- 对于真正的 CvLAC 编写测试，请使用虚拟项目，然后删除。
---
## 项目状态
- 已验证读取 7 个章节并对照实际导航。
- `update 支持 `add` / `update` / `delete`。
- 更改 `src/` 后 `dist/`。
有关内部开发的详细信息，请参阅 `CLAUDE.md`。
---
## 状态和路线图
读取 7 个章节、`diff`、重复项阻止和写入 `add`/`delete` 已针对实际 CvLAC 进行验证。`update`但未在生产中测试。
完整详情和后续计划： **[ROADMAP.md](ROADMAP.md)**。
实时导航发现（URL、表格列、字段名称、会话行为）： **[docs/cvlac-findings.md](docs/cvlac-findings.md)**。
