CvLAC (MinCiencias)

cvlac-mcp

AI アシスタントと会話するだけで、フォームに手入力せずに CvLAC を更新できます。

MinCiencias の CvLAC を入力するのは時間がかかります。講座、受賞、プロジェクトごとにフォームがあり、機関や自治体のカタログでは探している項目が見つからないこともあります。cvlac-mcp を使うと、AI アシスタント（たとえば Claude）に代わりに入力してもらえます。チャットで追加や修正を伝えると、アシスタントがあなたのアカウントで CvLAC にログインし、フォームに入力して保存し、正しく保存されたことを確認します。

お使いのコンピューター上で動作します。認証情報がコンピューターの外に出たり、中継サーバーを経由したりすることはありません。

• 利用イメージ
• できることとできないこと
• 必要なもの
• ステップごとのインストール — 約15分
• 依頼できること
• 安全性を守る仕組み
• よくある問題
• セキュリティとプライバシー
• 更新またはアンインストール
• 開発者向け

利用イメージ

会話は次のようなものです。

あなた： CvLAC に登録されている受賞歴を見せてください。

アシスタント： 6件あります。たとえば、「教職への貢献に対する表彰」（2023年）や「全国工学会議 最優秀発表賞」（2021年）などです…

あなた： これを追加してください：「教職への貢献に対する名誉賞」、Universidad del Norte、2024年、国内。

アシスタント： まだ保存していません。「教職への貢献に対する表彰」（2023年）と似ており、すでに CvLAC に登録されています。同じ受賞歴なので修正しますか、それとも別の受賞歴として新たに作成しますか？

あなた： 別のものです。作成してください。

アシスタント： 完了しました。CvLAC で保存が確認されました。リストに表示されています：「教職への貢献に対する名誉賞」、2024年、国内。

アシスタントは、事前に確認することなく項目を削除したり、重複した項目を作成したりすることはありません。この例の名前は架空のものです。

できることとできないこと

読み取り、追加、修正、削除ができます：

まだできないこと：

• **complete_productから証明書をアップロードすること：**この操作では、キーワード、分野、共著者、表彰、論文に紐づく学生を管理します。書籍の証明書はローカルパスを使ってupdate_sectionから添付します。complete_productのリストには含まれません。
• **CvLACのカタログに存在しない雑誌、書籍、出版社、プログラム、分野を作成すること。**カタログに複数の候補がある場合は、選択できるように表示します。
• **外国籍のアカウントでログインすること。**現時点では、ログイン時にコロンビア国籍を前提としています。
• 本人確認情報や住所、GrupLACに関する情報を変更すること。
• **CvLACに登録されていない補完的な研修プログラムを作成すること。**CvLACの検索では、その機関にすでに登録されているものだけが表示され、ウェブサイトでも新たに作成することはできません。

CvLACと別の情報源を自動的に比較する機能（diffツール）は、現在、特定の構造を持つウェブポートフォリオにのみ対応しています（詳細）。そのようなポートフォリオがなくても問題ありません。履歴書のテキストをチャットに貼り付けるか、口頭で伝えれば、アシスタントがCvLACを読み取り、不足している項目を一つずつ追加します。似ている項目がある場合は、その都度確認します。

必要なもの

• **CvLACのユーザー情報：**ウェブサイトへのログインに使う名前、身分証明書番号、パスワード。
• Windows、macOS、またはLinuxを搭載したコンピューター。
• **Node.js 20以降：**このツールを動かす無料のプログラムです。インストール方法は手順1にあります。
• **MCP サーバーに対応したAIアプリ。MCPは、このようなツールにAIアプリが接続するための標準規格です。対応アプリをお持ちでない場合は、まずClaude Desktop**をお試しください。最も簡単で、このガイドでも使用しています。Claude Code、Cursor、VS Code、Windsurf、Zed、JetBrainsも利用できます（接続方法）。

プログラミングの知識は必要ありません。ターミナルにコマンドをコピーして貼り付けるだけです。入力するコマンドはガイドにすべて記載されています。

インストール手順

**ターミナルとは？**コマンドを入力するウィンドウです。 **Windowsの場合：**Windowsキーを押し、「PowerShell」と入力して開きます。 **macOSの場合：**Cmd + スペースを押し、「Terminal」と入力して開きます。 コマンドを貼り付けるには、Windowsでは右クリック、macOSではCmd + Vを押します。その後、Enterキーを押してください。

ステップ 1 · Node.js をインストールする

nodejs.org から LTS バージョンをダウンロードし、チェック済みのオプションのままインストールします。その後、ターミナルを閉じてからもう一度開き、次を確認します。

node --version

v20 またはそれ以上の数字（例：v22.11.0）が表示されるはずです。

ステップ 2 · ツールが使用するブラウザーをダウンロードする

cvlac-mcp は、ウィンドウなしで動作するブラウザーである Chromium の専用コピーを使って CvLAC を操作します。ダウンロードは 1 回だけです（約 150 MB）。

npx -y cvlac-mcp@1 install-browser

最後に Chromium のインストールが完了したと表示されるはずです。

$env:NODE_OPTIONS="--use-system-ca"; npx -y cvlac-mcp@1 install-browser   # Windows (PowerShell)

NODE_OPTIONS=--use-system-ca npx -y cvlac-mcp@1 install-browser           # macOS / Linux

ステップ 3 · ログイン情報を保存する

ホームフォルダー内の別のテキストファイルに保存します。このファイルを読めるのはあなただけです。

Windows — PowerShell で次を実行します。

mkdir "$HOME\.config\cvlac-mcp" -Force
notepad "$HOME\.config\cvlac-mcp\.env"

メモ帳でファイルを作成するか尋ねられたら、はいと答えます。次の 3 行を貼り付け、引用符で囲まれた部分を自分の情報に置き換え、単一引用符はそのまま残して、Ctrl + S で保存します。

CVLAC_NOMBRE='Tu primer nombre'
CVLAC_CEDULA='1234567890'
CVLAC_PASSWORD='tu clave'

メモ帳を閉じ、ファイルを自分のユーザーだけが読めるようにします。

icacls "$HOME\.config\cvlac-mcp\.env" /inheritance:r /grant:r "${env:USERNAME}:(R,W)"

macOS / Linux — 単一引用符はそのまま残し、貼り付ける前に 3 つの値を変更します。

mkdir -p ~/.config/cvlac-mcp
cat > ~/.config/cvlac-mcp/.env <<'EOF'
CVLAC_NOMBRE='Tu primer nombre'
CVLAC_CEDULA='1234567890'
CVLAC_PASSWORD='tu clave'
EOF
chmod 600 ~/.config/cvlac-mcp/.env

• CVLAC_NOMBRE は、CvLAC に登録した名です。アクセント記号や ñ も含めて入力してください。
• 単一引用符は重要です。付けないと、パスワードに # が含まれている場合、そこから後が切り捨てられます。
• デスクトップやドキュメントのフォルダーが OneDrive または Google Drive と同期されている場合は、そこにこのファイルを保存しないでください。上記のフォルダーは同期されません。

$contenido = @'
CVLAC_NOMBRE='Tu primer nombre'
CVLAC_CEDULA='1234567890'
CVLAC_PASSWORD='tu clave'
'@
[IO.File]::WriteAllText("$HOME\.config\cvlac-mcp\.env", $contenido)

1. Claude Desktop を開き、設定 → 開発者 → 設定を編集（英語表示の場合： Settings → Developer → Edit Config）に進みます。ファイル claude_desktop_config.json があるフォルダーが開くので、メモ帳または TextEdit で開きます。
2. お使いのシステムに合ったブロックを貼り付け、TU_USUARIO をコンピューターのユーザー名に置き換えます。ユーザー名の確認方法：PowerShell では echo $env:USERNAME、macOS のターミナルでは whoami を実行します。

Windows:

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "cvlac-mcp@1"],
      "env": {
        "CVLAC_ENV_FILE": "C:\\Users\\TU_USUARIO\\.config\\cvlac-mcp\\.env"
      }
    }
  }
}

macOS（Linux では、パスの /Users/ を /home/ に置き換えます）：

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "npx",
      "args": ["-y", "cvlac-mcp@1"],
      "env": {
        "CVLAC_ENV_FILE": "/Users/TU_USUARIO/.config/cvlac-mcp/.env"
      }
    }
  }
}

3. 保存して、Claude Desktop を完全に終了します。ウィンドウを閉じるだけでは不十分です。Windows では、時計の横にあるアイコンを右クリックして → 終了を選択します。macOS では Cmd + Q を押します。その後、もう一度起動します。

よくある問題：

• ファイルにすでに内容がある場合は、置き換えないでください。既存の "mcpServers" の中に、カンマで区切って "cvlac-mcp": {...} を追加します。
• Windows では、ファイルが JSON 形式のため、パスのバックスラッシュは二重（\\）にします。Windows では npx はプログラムではなくスクリプトなので、cmd /c を前に付けます。
• CVLAC_ENV_FILE は必須です。ステップ 3 で作成したファイルの場所を cvlac-mcp に伝えます。

ステップ 5 · 動作を確認する

Claude Desktop で新しいチャットを開き、次のように入力します。

1. 「CvLAC にログインして」 — ログインしたという応答があるはずです。
2. 「CvLAC の学歴を表示して」 — すでに登録されている内容が一覧表示されるはずです。

両方とも動作すれば設定完了です。初回はパッケージのダウンロードがあるため、接続に約 15 秒かかることがあります。切断と表示された場合は、少し待ってから Claude Desktop を再起動してください。

うまくいきませんでしたか？ → よくある問題。

その他の AI アプリ

設定はどのアプリもステップ 4 と同じです。貼り付ける場所だけが異なります。

Claude Code:

# macOS / Linux
claude mcp add cvlac-mcp --scope user -e CVLAC_ENV_FILE=$HOME/.config/cvlac-mcp/.env -- npx -y cvlac-mcp@1

# Windows, desde Git Bash
MSYS_NO_PATHCONV=1 claude mcp add cvlac-mcp --scope user -e 'CVLAC_ENV_FILE=C:\Users\TU_USUARIO\.config\cvlac-mcp\.env' -- cmd /c npx -y cvlac-mcp@1

Git Bash では、MSYS_NO_PATHCONV=1 を指定しないと /c が C:/ に変換され、サーバーが接続できません。PowerShell から実行すると、PowerShell が -- を処理してしまうため、コマンドは unknown option '-y' エラーになります。Git Bash を使うか、引数の前に --% を付けるか、Windows 用の JSON を claude mcp add-json で貼り付けてください。

何を頼めばよいですか

スペイン語で、普段どおりに話しかけてください。たとえば、次のように頼めます。

ヒント：

• まず確認し、その後で変更してください。「何も保存せずに、何を追加するか教えて」と頼むのがおすすめです。
• **必要な情報をすべて伝えてください。**日付、機関、時間、範囲（国内または国際）などです。CvLAC が必須とする情報が不足している場合、アシスタントは推測で補わずに知らせてくれます。
• **登録内容は CvLAC で確認してください。**履歴書に記載された内容の責任はご自身にあります。アシスタントは保存するたびに確認しますが、依頼内容の解釈を誤ることもあります。

安全に利用するために

CvLAC には取り消しボタンがないため、cvlac-mcp は間違えるよりも、事前に確認することを優先します。

• **確認なしに重複登録することはありません。**追加しようとしている内容が既存の内容と似ている場合、何も登録せず、類似項目を表示します。
• **いきなり削除することはありません。**学術ネットワークや活動分野の削除も含め、すべての削除で再確認を求めます。
• **候補を勝手に選ぶことはありません。**機関名が CvLAC のカタログ内で複数の候補と一致する場合（「Universidad de los Andes」が 6 件あります）、候補を表示します。
• **情報を捏造することはありません。**情報が不足している場合、もっともらしい内容で補わずに知らせます。
• **結果を確認します。**フォームを送信しただけで保存済みとは判断せず、CvLAC の応答を確認し、不明な点があれば登録内容を再度読み取ります。保存の途中で CvLAC が停止した場合は、確認できなかったことを伝えるため、再試行する前に確認できます。
• **失敗した理由を伝えます。**CvLAC がフォームを拒否した場合、どのフィールドが、なぜ拒否されたのかを伝えます。
• **アカウントを保護します。**CvLAC がパスワードを拒否した場合、アカウントがロックされないよう再試行しません。また、CvLAC へのアクセス間隔を空け、サーバーに負荷をかけないようにします。

よくある問題

ほかに問題がありますか？issue を作成してください。ただし、個人情報を含むデータやスクリーンショットは添付しないでください。

セキュリティとプライバシー

具体的に、データはどう扱われるのでしょうか。

• 認証情報がコンピューターの外に出ることはありません。 認証情報は手順 3 のファイルに保存されます。cvlac-mcp は起動時に読み込み、ログインフォーム scienti.minciencias.gov.co にのみ入力します。
• 中継サーバー、アカウント、テレメトリー、分析機能はありません。 cvlac-mcp はコンピューター上のプログラムとして動作し、AI アプリと直接通信します。接続先は CvLAC、設定したポートフォリオ、および読み取り専用の DOI 検索をリクエストしたときの api.crossref.org のみです。
• AI アシスタントはあなたの履歴書を参照します。 認証情報は参照しません。cvlac-mcp が認証情報を返すことはありません。ただし、CvLAC から読み取った内容はチャットに送信されるため、AI アシスタントから参照できます。履歴書に機微な情報が含まれている場合は、アプリを選ぶ際に考慮してください。
• セッションはパスワードと同じくらい大切です。 各手順でパスワードを求めないよう、cvlac-mcp はユーザーフォルダー内の .cvlac-session.json にセッションを保存します。セッションが有効な間、このファイルをコピーした人は、パスワードなしで CvLAC にログインし、内容を変更できます。macOS と Linux では、ファイルはあなたのみが読み取れる状態で作成されます。Windows では、ユーザーフォルダーのアクセス許可を引き継ぎます。手動でアクセスを制限するには、次を実行します。 chmod 600 ~/.cvlac-session.json （macOS/Linux）または icacls "$HOME\.cvlac-session.json" /inheritance:r /grant:r "${env:USERNAME}:(R,W)" （Windows）。
• データファイルやセッションを、同期対象フォルダーに保存しないでください（OneDrive、Google Drive、Dropbox）。このガイドで説明する保存先は同期対象ではありません。
• セッションを終了するには、 .cvlac-session.json を削除してください。次回、cvlac-mcp が再度ログインします。
• ログに機密情報は表示されません。 デバッグのために詳細モードを有効にしても、パスワード、身分証番号、Cookie は *** と表示されます。CVLAC_LOG_FILE を設定した場合、ログファイルはあなたのユーザーのみがアクセスできるアクセス許可（0600）で作成されます。
• スクリーンショットには個人情報が含まれる場合があります。 共有する前に確認してください。
• 認証済みのブラウジングは CvLAC に限定されています。 inspect_form、screenshot、内部リンクで許可されるのは scienti.minciencias.gov.co の HTTPS のみです。file://、他のホスト、削除や保存などの操作リンクは拒否されます。
• ブラウザーでは、デフォルトで Chromium のサンドボックスが有効です。 サンドボックスを有効にして起動できない環境に限り、追加のリスクを理解したうえで CVLAC_NO_SANDBOX=true を明示的に設定してください。
• 情報が漏えいした疑いがある場合は、 CvLAC のパスワードを変更し、セッションファイルを削除してください。

責任ある利用

• これは、あなた自身のアカウントとデータを使ってコロンビアの政府機関のウェブサイトを自動化するものです。認証を回避したり、他人の履歴書にアクセスしたり、非公開 API を使用したりすることはありません。ブラウザーであなたが行う操作を、より速く実行します。
• 使用前に、ScienTI/MinCiencias の利用規約と所属機関のポリシーを確認してください。
• 常に人が監督してください。 変更を適用する前に内容を確認し、見守らずに実行させたり、自動実行するように設定したりしないでください。
• 複数のアカウントで並行して実行したり、リクエストの頻度を上げたりしないでください。
• 履歴書に記載される内容は、あなたの責任です。 公募や評価に影響する申告内容です。CvLAC で記載内容を確認してください。

独立したプロジェクトです。 MinCiencias とは提携しておらず、同機関からの支援も受けていません。同機関のロゴやビジュアルアイデンティティを再現していません。上のシンボルは独自のデザインで、収束する線で描いた輪の中に JSON-RPC の中括弧 { } を配置しています。「CvLAC」、「ScienTI」、「MinCiencias」の名称は、このサーバーが通信するシステムを識別する目的でのみ使用しています。

更新またはアンインストール

• **更新：**何もする必要はありません。cvlac-mcp@1 を使うと、AI アプリを開くたびに最新の 1.x バージョンが使用されます。2.x がリリースされた場合は、設定で @1 を @2 に変更してください（先に ROADMAP で変更点を確認してください）。
• バージョンの確認：npx -y cvlac-mcp@1 --version。
• **アンインストール：**アプリの設定から "cvlac-mcp" ブロックを削除し、ユーザーフォルダー内の .config/cvlac-mcp フォルダーと .cvlac-session.json ファイルを削除してください。

開発者向け

以下の内容は、コードを監査したい方、貢献したい方、MCP ツールを直接使いたい方、または CvLAC とウェブポートフォリオを比較したい方向けです。

TypeScript + Playwright で実装された stdio MCP サーバーです。厳格な ESM を採用し、Linux、Windows、macOS で Vitest によるテストを実施しています。検証済みの内容、不足している点、既知の制限については、ROADMAP をご覧ください。

• ソースコードからインストール
• 高度な設定
• ポートフォリオとの比較（diff と sync）
• MCP ツールリファレンス
• 環境変数
• アーキテクチャ
• テストとビルド
• 開発に関する問題
• ステータスとロードマップ

ソースコードからインストール

コードの開発、貢献、監査を行う方向けです。サーバーを使うだけの場合は、手順に沿ったインストールのほうが簡単です。環境に問題がないことを確認しながら進められるよう、各手順には検証方法が含まれています。順番に実行してください。

手順 0 - 前提条件（すべてのプラットフォーム）

Node.js 20 以上、npm 10 以上、git が必要です。

確認（bash、zsh、PowerShell のいずれでも実行できます）：

node --version   # debe mostrar v20.x o superior
npm --version    # debe mostrar 10.x o superior
git --version

手順 1 - リポジトリをクローン

Linux / macOS（bash または zsh）：

cd ~/dev            # o la carpeta que prefieras
git clone https://github.com/stivenson/cvlac-mcp.git
cd cvlac-mcp

Windows（PowerShell）：

cd $HOME\dev        # crea la carpeta antes si no existe: mkdir $HOME\dev
git clone https://github.com/stivenson/cvlac-mcp.git
cd cvlac-mcp

手順 2 - 依存関係をインストールしてビルド

3 つのプラットフォームで共通です：

npm install
npm run build

**確認：**コンパイル済みのエントリーファイル dist/index.js が存在する必要があります。

# Linux / macOS
ls dist/index.js

# Windows (PowerShell)
Test-Path dist\index.js   # debe imprimir True

手順 3 - Playwright のブラウザーをインストール

サーバーはヘッドレス Chromium を使って CvLAC を自動操作します。プロジェクトで使用している Playwright のバージョンに対応するビルドをダウンロードします：

node dist/index.js install-browser

Linux でシステムライブラリが不足している場合は、ネイティブの依存関係もインストールしてください：

npx playwright install-deps chromium   # requiere sudo en algunas distros

手順 4 - 環境変数を設定（.env）

テンプレートをコピーし、値を編集します：

Linux / macOS：

cp .env.example .env

Windows（PowerShell）：

Copy-Item .env.example .env

.env を自分のデータで編集します：

CVLAC_NOMBRE='TuNombre'
CVLAC_CEDULA='TuDocumento'
CVLAC_PASSWORD='TuPassword'
PORTFOLIO_URL='https://tu-usuario.github.io'
# Opcional: por defecto, .cvlac-session.json en tu carpeta de usuario
# CVLAC_SESSION_PATH='/ruta/a/tu/.cvlac-session.json'

ファイルのアクセス権を制限します（Linux/macOS）：

chmod 600 .env

Windows で chmod に相当するコマンドは icacls .env /inheritance:r /grant:r "${env:USERNAME}:(R,W)" です。

プラットフォームごとの CVLAC_SESSION_PATH（変更する場合の例）：

• Linux：/home/TU_USUARIO/.cvlac-session.json
• macOS：/Users/TU_USUARIO/.cvlac-session.json
• Windows：C:\\Users\\TU_USUARIO\\.cvlac-session.json

ステップ 4b - デフォルト値を設定する（cvlac.config.json）

CvLAC の複数のフォームでは、ポートフォリオにない項目（市区町村、週間授業時間数、言語）が必須です。これらの項目はここで一度だけ宣言します。

cp cvlac.config.example.json cvlac.config.json

{
  "portfolioUrl": "https://tu-usuario.github.io",
  "defaults": {
    "municipio": { "nombre": "Bogotá", "codigoDane": "11001" },
    "institucionFallback": "Universidad Nacional de Colombia",
    "horasSemanales": 1,
    "idioma": "ES",
    "pais": "CO"
  }
}

すべて任意です。値がない場合、フィールドは空欄になり、レスポンスに警告が含まれます — サーバーが履歴書のデータを捏造することはありません。

ステップ 4c - プロジェクト、ソフトウェア、イベントを整理する（data/portfolio-extra.json）

この 3 つのセクションはポートフォリオから読み取れません。CvLAC にしかないメタデータ（プロジェクトの種類、DANE コード、列挙型のコード）が必要なため、手動で管理します。

cp data/portfolio-extra.example.json data/portfolio-extra.json

ファイルは読み込み時に検証されます。項目の形式に誤りがあった場合は、サーバーが報告し、残りのセクションの処理を続行します。

ステップ 5 - アプリに MCP を登録する

手順に沿ったインストールと同様ですが、npx を node に、パスを dist/index.js に変更します。CVLAC_ENV_FILE は不要です。リポジトリをクローンした場合、サーバーはリポジトリのルートにある .env を読み込みます。

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "node",
      "args": ["/home/TU_USUARIO/dev/cvlac-mcp/dist/index.js"]
    }
  }
}

• macOS： "/Users/TU_USUARIO/dev/cvlac-mcp/dist/index.js"
• Windows： "C:\\Users\\TU_USUARIO\\dev\\cvlac-mcp\\dist\\index.js"（JSON ではバックスラッシュを二重にします。node は実行可能ファイルなので、ここでは cmd /c は不要です）
• Claude Code： claude mcp add cvlac-mcp --scope user -- node /ruta/a/cvlac-mcp/dist/index.js
• 各アプリでの JSON の配置場所： その他の AI アプリ。

認証情報は .env にのみ保存してください。 アプリの設定ファイルは、アクセス権限が制限されていなかったり、マシン間で同期されていたりすることがよくあります。それでも env ブロックに記載した場合は、.env より優先されます。

ステップ 6 - インストールを確認する

1. ビルドとテストがすべて成功すること：

   npm run build
   npm test
   

2. サーバーの起動（簡易チェックです。stdio で待機するため、Ctrl+C で終了します）：

   node dist/index.js
   

3. エディターで確認： エディターを再起動し（Claude Desktop は完全に終了する必要があります）、cvlac-mcp が有効になっていて、ツールの一覧が表示されることを確認します。Cursor では Settings → MCP、Claude Code では claude mcp list または /mcp、VS Code ではエージェントチャットのツール選択メニューを確認してください。

4. エディターのチャットから、次の順に最小限の動作確認を行います：

   • login（認証され、セッションが保存されること）
   • read_cvlac に section: "formacion" を指定（CvLAC に登録済みの内容が返されること）
   • ポートフォリオを設定した場合は、read_portfolio の後に diff

エラーなく応答すれば、MCP は正しくインストールされ、設定されています。

詳細設定

サーバーの利用に、これらの設定は必要ありません。npx でインストールした場合は、各ファイルのパスを、アプリの設定にある CVLAC_ENV_FILE と同じ env ブロック内の変数で指定します。リポジトリをクローンした場合は、リポジトリのルートから読み込まれます。

.env と一緒に ~/.config/cvlac-mcp/ に保存することをおすすめします。デフォルト値がない場合、フィールドは空欄になり、レスポンスに警告が含まれます。サーバーが履歴書のデータを捏造することはありません。

ポートフォリオとの比較（diff と sync）

diff は CvLAC とウェブポートフォリオを比較し、各項目を 不足、更新が必要、類似（似た項目がすでに存在します。人が判断してください）、最新 の4つのグループに分類します。sync はデフォルトでプレビューを表示し、dry_run: false を指定して呼び出した場合にのみ、不足分と更新が必要な項目を適用します。類似項目は適用しません。

重要な制限事項： read_portfolio は特定のサイト向けに作られています。具体的には、#/resume パス、Experiencia、Educación、Cursos のタブ、「Logros Destacados」セクションがある React アプリです。この構造が見つからない場合は、ログに警告を記録して空のリストを返します。プロジェクト、ソフトウェア、イベントはサイトから取得せず、portfolio-extra.json から取得します。次の項目も diff の対象外です。職歴（企業名が大きく異なるため）、言語、研究分野、その他の業務。

ソースをエンジンから分離し、PDF、ORCID、ディクテーションのいずれから取得した場合でも、diff が正規化された履歴書 JSON を受け取れるようにすることは、ROADMAP に記載されています。

推奨されるワークフロー：

1. login
2. dry_run: true で sync を実行
3. レポートを人が確認：不足分、更新が必要な項目、類似項目、最新の項目
4. 類似項目を1つずつ解決 — 既存項目に対して update を実行するか、confirm_duplicate:true を指定して add を実行
5. 残りを適用：dry_run: false で sync を実行するか、項目ごとに update_section を実行し、warnings を確認
6. 更新したセクションで read_cvlac を実行するか、read_cvlac_detail で確認

read_portfolio ─┐
                ├─► diff ─► sync (dry_run → apply) ─► update_section (add / update / delete)
read_cvlac ─────┘

Claude Code を使用している場合は、 クライアントワークスペースの cvlac-sync スキルで、このワークフローを一括して実行できます。

MCP ツールリファレンス

ツールが失敗すると isError: true を返します。needs_confirmation と unverified はエラーではなく、人による判断または確認を求めるものです。

complete_product

labelで既存の製品を見つけ、操作には次の1つ以上の完全なリストを渡します。

• keywords：順序付きキーワード。
• areas：CvLACの名称またはコードで指定する、順序付きの知識分野。
• coauthors：あらかじめ登録されたプロフィールカタログから選択した、順序付きの共著者名。 履歴書の所有者は自動的に保持されます。
• recognitions：CvLACの履歴書にすでに登録されている、順序付きの表彰タイトル。
• students：tesisの場合のみ。{name, participation, person_id?}オブジェクトです。participationには TUT、ASE、COT、ORI、またはそれぞれのラベル（Tutor、Asesor、Cotutor、Orientado）を指定できます。省略すると、 ORIが使用されます。

リストを渡すと、保存済みの値が置き換えられます。既存の値が削除される場合は、まずremovedを含むneeds_confirmationが返されます。confirm_delete:trueを指定して再実行してください。人物が特定できない場合や、該当するプロフィールが複数ある場合は、choicesが返され、何も書き込まれません。

update_section

セクション：formacion、formacionComple、experiencia、cursos、reconocimientos、proyectos、 software、eventos、idiomas、lineas、demasTrabajos、articulos、libros、capitulos、 tesis、jurados、informesTecnicos、innovacionesProceso、productosTecnologicos、consultorias、 prototipos。各セクションのdataスキーマは src/schemas.tsにあります。不正な形式のフィールドは、ブラウザーを開く前に、フィールド名を示して拒否されます。

詳細：

• フォームのフィールドを1つも変更できないupdateは送信されません。警告とともにfailedが返されます。
• 完全一致する機関は自動的に特定されます。ただし、カタログには完全一致する重複項目（「Universidad de los Andes」が6件）があります。そのため、名称だけでは特定できない場合があります。
• formacionCompleはformacionと同じフォームを使用しますが、レベルのカタログ（Y Otros、8 Extensión、F Cursos de corta duración、E MBA）とstartMonthが異なります。addが機能するのは、その機関とレベルについてCvLACにすでに登録されている学術プログラムのみです。
• libros：certificateCLCDOとcertificateCLRIは、実際のフォームで使用する2つの証明書PDFを指定する任意のローカルパスです。送信前に、%PDF-の署名、拡張子、ファイルの存在、2 MiBの上限が検証されます。CvLACはこれらのファイルをフォームの値として返さないため、証明書だけを編集するとunverifiedが返されることがあります。再試行する前に記録を確認してください。
• demasTrabajos：name、year、month、medio（Papel、InternetまたはOtro）、finalidad。idiomaとciudadは任意です。フォームでは「Enero」と「Papel」があらかじめ選択されています。monthまたはmedioを省略すると、それらが保存され、その旨が通知されます。
• idiomas：language（スペイン語名または2文字のISOコード）、およびread／write／speak／listenのレベル、またはすべてのレベルを一括設定するlevel（Deficiente、AceptableまたはBueno）。
• lineas：name、active（既定値はtrueで、その旨が通知されます）、objective。
• experiencia：CvLACのフォームには役職のフィールドがありません。項目にroleが含まれている場合、書き込まれなかったことが通知されます。

update_profile

• description はプロフィールテキストを置き換えます。空にすることはできません。CvLAC では必須項目として扱われます（最大 3950 文字）。
• networks は保存済みの内容とマージされます。CvLAC のフォームはテーブル全体を書き換えるため、ツールはまず内容を読み取り、すべて再送信します。url:null はネットワークを削除し、confirm_delete:true が必要です。使用可能なネットワーク：google_scholar、researchgate、ssr、ssrn、academia_edu、mendeley、linkedin、repositorios_disciplinares、repositorios_institucionales、researcher_id、scopus_author_id、orcid、otro（名前を label に指定します）。
• areas は順序を含む活動分野の完全なリストです。最初の項目が主要分野になります。CvLAC の名称またはコード（0-1B01）で指定します。保存済みの内容を置き換えるため、項目を省くと削除され、confirm_delete:true が必要です。カタログには 3 階層にわたる 267 の分野があります。名称が曖昧な場合は推測せず、choices を返します。

環境変数

.env、またはアプリの設定にある env ブロックで定義します。アプリの設定が優先されます。

起動時に、サーバーは読み込んだ .env を stderr に出力します。 env file: <ruta> (found, 3 vars)、または NOT FOUND と表示されます。UTF-8 以外の場合は read as utf16le または read as latin1 と表示されます。

リクエスト間隔

リクエストが連続して到着すると、CvLAC は 5xx を返し始めます。サーバーはページ遷移の間隔を空け、バックオフを使って再試行します。サイトが連続して複数回リクエストを拒否した場合は、クールダウンが終わるまで再試行を停止します。デフォルト値は通常の sync に適しています。503 が続く場合は値を大きくしてください。

アーキテクチャ

src/
├── index.ts                  # Entry point: subcomandos, carga del .env, stdio transport
├── cli.ts                    # install-browser, --version, --help
├── env.ts                    # Ubicación y lectura del .env (UTF-8, UTF-16 o ANSI)
├── server.ts                 # Registro de tools MCP, isError
├── types.ts                  # Tipos de portfolio/CvLAC/diff/update
├── schemas.ts                # Un schema zod por sección
├── config.ts                 # cvlac.config.json
├── logger.ts                 # Logs a stderr, con secretos ocultos
├── diff.ts                   # Motor de comparación (normalize + nameMatches)
├── browser/
│   ├── session.ts            # Login, sesión persistente, Playwright context
│   ├── navigation.ts         # URLs de listas y formularios CvLAC
│   ├── navigate.ts           # Toda navegación: ritmo, reintentos, cortes
│   ├── pacing.ts             # Espaciado de peticiones y backoff
│   ├── availability.ts       # Distingue "CvLAC caído" de un error propio
│   └── catalogue.ts          # Catálogos de CvLAC (municipios, instituciones)
├── tools/
│   ├── login.ts  read-cvlac.ts  read-cvlac-detail.ts  read-portfolio.ts  diff.ts  sync.ts
│   ├── update-section.ts     # add/update/delete por sección
│   ├── write-verdict.ts      # ¿Se guardó? saved / rejected / unverified
│   ├── profile.ts            # Perfil y redes académicas
│   ├── areas.ts              # Áreas de actuación
│   └── screenshot.ts
└── extractors/
    ├── portfolio.ts          # Renderiza el portafolio + portfolio-extra.json
    └── cvlac/                # Un extractor por sección, sobre rows.ts

設計上の判断や、バグの原因になった CvLAC の落とし穴については CLAUDE.md をご覧ください。また、実環境で確認した URL、列、フィールド名については docs/cvlac-findings.md をご覧ください。

テストとビルド

npm test          # suite completa: sin red, sin credenciales, sin CvLAC
npm run build     # compila src/ a dist/, que es lo que ejecuta la app
npm run dev       # corre src/ con tsx, sin compilar
npm run test:watch

テストでは、抽出器（匿名化した HTML フィクスチャを使用）、差分エンジン、スキーマ、設定と .env の読み込み、ログ内のシークレットのマスキング、sync のレポート、MCP 境界、詳細レコードの読み込みを対象としています。フィクスチャには意図的に架空のデータを使用しています。新しいフィクスチャ用に実際の HTML を取得した場合は、コミットする前に匿名化してください。

smoke ワークフローは Linux、Windows、macOS で実行されます。ビルド、テストの実行、install-browser による Chromium のインストールを行い、起動、MCP プロトコル、登録済みツール、認証情報を含まないメッセージ、ブラウザーの起動を確認する scripts/smoke.mjs を実行します。別のジョブでは PowerShell 5.1 と 7 で一般的な 3 つの方法を使って .env を作成し、サーバーが読み込めることを確認します。手動で実行した場合は、npm からインストールした状態のパッケージもテストします。

ライブテストスイート（任意。実際の CvLAC に書き込みます）

CVLAC_E2E=1 npm run test:e2e:live                      # las secciones con lista
CVLAC_E2E=1 npm run test:e2e:live -- --sections=cursos  # solo una
CVLAC_E2E=1 npm run test:e2e:live -- --sections=perfil  # perfil y redes

実際のアカウントを使って、各セクションの CRUD 全体を実行します。リスト → add → リスト → read_cvlac_detail → add（繰り返しの場合は needs_confirmation を返す必要があります）→ update → 詳細で変更を確認 → delete → 最終リスト、の順です。作成する各項目には ZZ PRUEBA MCP というプレフィックスが付き、必ず削除を試みます。残った項目があれば、最後に報告するので手動で削除してください。--sections=perfil はスナップショットを取得し、誰も使っていないネットワークに書き込み、編集、削除した後、元の状態に戻します。

実データに触れる唯一のテストスイートのため、CVLAC_E2E=1 が必要であり、npm test では実行されません。dist/index.js と通信するため、npm run build の後に実行してください。レポートは tests/e2e/report-<fecha>.json に保存されます（gitignore 対象）。

開発時の問題

• アプリで古いコードが使われる： src/ の変更後に npm run build を実行してください。アプリが実行するのは src/index.ts ではなく dist/index.js です。
• アプリに表示されない（クローンしたリポジトリからのインストール）： args 内の dist/index.js の絶対パスを確認してください。Windows ではバックスラッシュを二重にし、アプリを再起動してください。
• フォームでフィールドが保存されない： CvLAC の複数のフィールドは readonly で、JavaScript によって入力されます。実際の名前を確認するには inspect_form を使い、ブラウザーを表示するには CVLAC_HEADLESS=false を設定し、各フィールドの詳細を確認するには CVLAC_LOG_LEVEL=debug を設定してください。
• diff で誤検出される欠落： nameMatches() はアクセント記号と接尾辞（(en línea)、 - Aprobado ...）を正規化します。経験は意図的に diff の対象外です。

状態とロードマップ

元の 11 セクション、プロフィール、学術ネットワーク、活動分野は読み書き（add／update／delete）に対応しており、実際の CvLAC で CRUD を検証済みです。記事、書籍、章、論文、審査委員、技術成果の各セクションも実装済みです。実データでの CRUD 全体は記事で検証済みです。技術レポートとコンサルティングでは、追加、一覧、詳細、重複ブロック、削除を検証済みです。一部の編集フィールドは実際のフォームの差異に依存し、ロードマップに記載されています。diff と重複ブロックは、JMesa ページネーションによる全リストにも対応しています。

complete_product は既存の成果にキーワード、分野、共著者、謝辞を追加し、論文の学生をその参加情報に紐付けます。書籍の update_section では、ローカルパス certificateCLCDO と certificateCLRI も指定できます。各 PDF のサイズは最大 2 MiB です。この操作は一時レコードを使った E2E テストで検証済みです。

詳細、既知の制限、今後の予定については、ロードマップ をご覧ください。