MCP 服务器

poranos-mcp-ainpc

Enables Claude Desktop/Code to read and edit Poranos AI NPC scenarios and conversation logs via natural language, including scenario versioning and audit logging.

README

poranos-mcp-ainpc

Claude Desktop / Claude Code から Poranos AI NPC のシナリオ・会話ログを操作するための MCP (Model Context Protocol) サーバ。

非エンジニアの運用担当が会話ログを読みながら自然言語で「Sub が冒頭で『なるほど』と言ってる、修正して」と Claude に伝えれば、Claude が必要なツールを呼び出してシナリオの prompt を編集する — というワークフローを実現する。

何ができるか

会話ログ閲覧 → 違反抽出 → プロンプト編集 → 履歴記録までを Claude Desktop / Claude Code 内で完結させる:

シナリオの一覧・詳細取得・編集 (PATCH)
シナリオの複製、過去版へのロールバック
編集履歴 (audit log) の閲覧
会話ログの一覧・詳細取得 (Unity からアップロードされたセッションログ)

全編集は poranos.com 側の ScenarioVersion に edit_source='mcp' で自動記録され、Web 管理画面の「履歴」セクションから 1-click でロールバック可能。

セットアップ

1. API キーを発行する

https://poranos.com/app/account/ にログインし、「AI NPC API キー」セクションから新しいキーを発行する。

アクセスレベルは 「閲覧 + 編集」 (ai-npc:write) を推奨。「閲覧のみ」を選ぶと編集系の Tool が 403 を返す
発行直後に表示される pk_... を必ずコピーして保管する (二度と表示できない)

2. uv のインストール (まだなら)

uvx は uv に同梱されています。

Linux / macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Claude Desktop の設定

設定ファイルに以下を追加:

Linux: ~/.config/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "poranos-ainpc": {
      "command": "uvx",
      "args": ["poranos-mcp-ainpc"],
      "env": {
        "PORANOS_API_KEY": "pk_あなたのキー"
      }
    }
  }
}

設定を保存したら Claude Desktop を再起動。

メモ: 初回起動時に uvx が PyPI からパッケージを fetch するため少し時間がかかります (5-15 秒)。2 回目以降はキャッシュされます。

Windows で command: "uvx" が見つからないと言われる場合は、uvx のフルパス (例: C:\\Users\\<user>\\.local\\bin\\uvx.exe) を指定してください。

Claude Code で使う場合

claude mcp add poranos-ainpc \
  -e PORANOS_API_KEY=pk_あなたのキー \
  -- uvx poranos-mcp-ainpc

ローカル開発

git clone https://github.com/kkoba23/poranos-mcp-ainpc.git
cd poranos-mcp-ainpc
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# 環境変数で API キーをセット
export PORANOS_API_KEY=pk_あなたのキー

# サーバー起動 (stdio transport)
poranos-mcp-ainpc

提供される MCP Tools

Scenario 系

Tool	用途
`list_scenarios()`	シナリオ一覧
`get_scenario(scenario_id)`	シナリオ詳細 (focus_block_template / role_addendums 等を含む)
`create_scenario(fields)`	新規シナリオ作成 (name 必須、他はサーバ既定値)
`update_scenario(scenario_id, fields)`	シナリオを部分更新 (PATCH)
`duplicate_scenario(scenario_id)`	シナリオを private コピーとして複製
`get_scenario_versions(scenario_id)`	編集履歴 (meta のみ)
`get_scenario_version(scenario_id, content_version)`	特定版の snapshot
`rollback_scenario(scenario_id, content_version, note?)`	過去版に戻す

Personality 系

Tool	用途
`list_personalities()`	NPC 人格 (Personality) 一覧
`get_personality(personality_id)`	人格詳細 (system_prompt / voice / character_id 等)
`create_personality(fields)`	新規人格作成 (name / system_prompt / character_id 必須)
`update_personality(personality_id, fields)`	人格を部分更新

ConversationLog 系

Tool	用途
`list_conversation_logs(scenario_id?, personality_id?, since?, until?)`	会話ログ一覧 (フィルタ可)
`get_conversation_log(log_id)`	会話ログ詳細 (utterances / personalities_snapshot / metadata)

提供される MCP Prompts (定型ワークフロー)

Prompt	用途
`analyze_log(scenario_id, log_id)`	ログを scenario と照合して違反を抽出
`propose_edit(scenario_id, feedback)`	自然言語フィードバックから編集案を提案 → 承認 → 反映
`create_scenario_guide(intent)`	新規シナリオを「執筆ガイドを踏まえて」作成

これらは Claude Desktop の / メニュー (slash commands) から呼び出せる。全ての prompt は処理開始前に prompt 執筆ガイド (下記 Resource) を読むよう Claude に指示する。

提供される MCP Resources (静的参考資料)

URI	内容
`poranos://prompt-authoring-lessons`	Scenario の `focus_block_template` / `role_addendums` 等を書くときの実践ガイド (Markdown)。Realtime モデルの素の癖、典型的な落とし穴、効くテクニックを集約

ツール経由でも同じ内容を取得可能 (get_prompt_authoring_lessons())。 Claude Desktop の UI から直接閲覧 / コンテキスト添付できる他、prompt の指示で内部的に resources/read 経由で読む。

典型的な使い方

Claude Desktop を開く
/propose_edit を選択 (または「Library Tour の昨日のログを見て、Sub が冒頭で『なるほど』と言ってるから直して」のように直接話しかける)
Claude が list_scenarios → list_conversation_logs → get_conversation_log で材料を集める
Claude が違反を抽出して報告し、編集案 (diff) を提示
ユーザーが「OK」と承認
Claude が update_scenario を呼んで反映、get_scenario_versions で履歴記録を確認