Skip to content

User_Guide(Local_MCP_Edition)[JP]

Jump to bottom
Yusuke Ogawa (yuogawa) edited this page May 11, 2026 · 3 revisions

User Guide (Local MCP Edition) [日本語]

Network Sketcher Local MCP は、同じエンジンをローカル Model Context Protocol サーバとして公開し、AI エージェント (Cursor / Claude Code) からツール呼び出しでネットワーク設計を行える版です。Ver 3.1.0 で追加されました。

概要、機能、要件、インストール手順、AI クライアントからの接続設定は README - Network Sketcher Local MCP を参照してください（README は英語）。本ページではサーバ起動後に必要なすべての情報を扱います。

起動確認

python ns_mcp_server.py

サーバは stdio で待機し続けます — これは正常な動作です（終了は Ctrl+C）。ログは stderr に出力されます。

設定 (mcp_config.json)

Key Description
working_directory 任意。 空でないパスを設定すると、起動時にそのパスが初期ワークスペースとして使用されます。空のまま（推奨）にした場合は、サーバはアクティブなワークスペースなしで起動し、AI エージェントは他の Tool を使う前に suggest_workspace() → set_workspace(path) を呼び出す必要があります。OS 非依存の可搬性のため、空にすることを推奨します。
log_level DEBUG / INFO / WARNING / ERROR
ai_context_show_commands get_network_state Tool が実行する show コマンドのリスト
command_timeout_seconds （予約済み；現バージョンでは未使用）

マスタファイル形式: .nsm のみ

本エディションは .nsm (ZIP + Apache Parquet) マスタファイルのみを扱います。openpyxl を経由した .xlsx アクセスは大規模ネットワークでは低速のため、import/export の境界でのみ使用します。

  • 既存の .xlsx マスタを使う場合 → import_master で変換
  • Excel または Offline 版で開きたい場合 → export_master_xlsx で書き戻し
  • 新規にマスタを作成する場合 → create_empty_master が .nsm を直接生成

公開 Tools

Tool Role
suggest_workspace 現在の OS (Windows / macOS / Linux) に適したワークスペース候補ディレクトリを返す
set_workspace 指定パスをこのセッションの作業ディレクトリに設定（home 配下のパスのみ許可、無ければ自動作成）
get_workspace_info 作業ディレクトリと、その中のマスタ／出力ファイル一覧を返す（ワークスペース未設定なら workspace_active=false を返す）
create_empty_master 空の [MASTER]<name>.nsm を作成（内部で xlsx → nsm 変換し xlsx は破棄）
import_master 既存の .xlsx を作業ディレクトリ内で .nsm に変換
export_master_xlsx .nsm から .xlsx を生成（Excel または Offline 版で編集するため）
get_network_state 主要な show コマンドを実行し集約結果を返す（軽量）
get_ai_context [AI_Context]<name>.txt を生成しその内容全体を返す（フルコンテキスト）
run_commands 複数の add / rename / delete / show コマンドを 1 回の呼び出しで実行
export_diagram L1 / L2 / L3 図を SVG または PPTX 形式で生成

公開 Prompts

Prompt Role
start_ns_session(master) セッション開始テンプレート。AI を get_workspace_info → get_ai_context → サマリ報告のワークフローに強制的に乗せる。
  • Cursor では /start_ns_session スラッシュコマンドで起動。
  • Claude Code では /mcp__network-sketcher__start_ns_session で起動（Claude Code の MCP プロンプト命名規則 /mcp__<server>__<prompt> に準拠）。

公開 Resources

URI Content
nsm://workspace 現在の作業ディレクトリ状態 (JSON)
nsm://commands CLI コマンド全リファレンス (nsm_extensions_cmd_list.txt)

AI Context ガイダンス機構

LLM が現在の状態を把握しないままコマンドを発行することを防ぐため、3 層のガイダンスを設けています。

  1. サーバ instructions（自動）： FastMCP 初期化時に instructions が MCP ホストへ送信されます。Cursor および Claude Code はこれをシステムプロンプトに含めるため、AI は新規セッションごとに自動的に get_workspace_info → get_ai_context を呼び出すよう促されます。instructions はさらに、現在のサブタスクに関連する能力を持つホスト登録済み MCP サーバがあれば、Network Sketcher の変更操作を行う前にそれを呼び出すことを 必須 としています（後述の Additional Policy 参照）。
  2. /start_ns_session プロンプト（明示起動）： スラッシュコマンドで起動された場合、ステップバイステップのメッセージが挿入され、AI をワークフローへ誘導します。最初のステップで AI は他の登録済み MCP サーバを列挙し、関連性マッピングをユーザに提示することが要求されます。
  3. Tool docstring の PREREQUISITE（フェイルセーフ）： run_commands および export_diagram の docstring は、get_ai_context を先に呼び出さなければならない旨を明記しています — AI が docstring を読んだ際の最後の安全網です。

Additional Policy: Coordinated Use of Other MCP Servers (Mandatory)

サーバ instructions と /start_ns_session プロンプトには、ホストに登録された すべての MCP サーバ（ドキュメント／RAG サーバに限らず、ベンダーやカテゴリを問わず構成・監視・課題管理・チャット・リポジトリ等を含む）を対象とする以下のポリシーが含まれています。

  • 強制レベル： 「関連する場合は MANDATORY」。サブタスク開始前に LLM は「ホスト登録済みのいずれかの MCP サーバの能力がここに関連するか？」と自問しなければなりません。Yes であれば、Network Sketcher の変更操作を行う 前 にそのサーバを呼び出し、最終回答で返ってきた情報源を 引用 しなければなりません。
  • 関連性の判断： サーバ名のみではなく、各サーバの説明 (serverUseInstructions / tool descriptors) に基づいて行います。
  • 典型的な関連性マッピング（網羅的ではない）：
    • ドキュメント／RAG サーバ → モデル選定、ベストプラクティス、EoS/EoL、設定例、トラブルシューティング
    • トポロジ／設定／監視サーバ → 実機状態に基づく設計判断の裏付け
    • 課題管理／チャット／リポジトリサーバ → ユーザの要求が既存チケット・コード・履歴を参照している場合
  • 濫用防止のガードレール：
    • タスクと明らかに無関係な能力のサーバは呼び出さない
    • MCP サーバの認証は 1 つずつ実行（並列認証はしない）
    • 1 ユーザターンあたり外部 MCP 呼び出しは概ね 10 件以下 に抑える
    • 失敗時はユーザに報告し、無限リトライせず残りの情報源で続行する
  • 適用範囲： 本ポリシーは Local MCP エディション専用です（Online / Offline エディションは MCP ホスト経由でアクセスされないため対象外）。共有される AI Context 成果物 ([AI_Context]<name>.txt) には含まれません。

ワークスペース選択（クロスプラットフォーム）

本エディションは OS 固有のパスをハードコードしません。AI エージェントが OS を検出し、ホストに適したディレクトリを提案します。

既定動作（推奨）

  1. mcp_config.json の working_directory を空 ("") に設定
  2. セッション開始時に AI が suggest_workspace() を呼び出し、OS 別の候補を取得：
    • Windows: ~/Documents/ns_workspace, ~/Desktop/ns_workspace, ~/ns_workspace
    • macOS: Windows と同じ
    • Linux: $XDG_DATA_HOME/ns_workspace (もしくは ~/.local/share/ns_workspace), ~/Documents/ns_workspace, ~/ns_workspace
  3. AI が候補を 1 つユーザに提案し、確認を求める
  4. ユーザの承認後、AI が set_workspace(path) を呼び出す
  5. それ以降のセッション全体で全 Tool が当該ワークスペース上で動作

高度な使い方（固定ワークスペース）

複数のホストで同一パスを共有したい場合や常に固定ディレクトリを使いたい場合は、mcp_config.json の working_directory に絶対パス（または ~/...）を設定します。起動直後にワークスペースが有効になるため suggest_workspace / set_workspace を呼ぶ必要はありません。

セキュリティ境界

set_workspace(path) が受け付けるのは、以下のすべてを満たすパスのみです：

  • Path.home() (~/ / $HOME) 配下に解決される
  • 書き込み可能である
  • 存在しなければ自動作成される

ホストシステムへの意図しないアクセスを防ぐため、home ディレクトリ外のパスは拒否されます。

標準的な利用フロー (Local MCP)

  1. （初回のみ）mcp_config.json の working_directory を空にするか、固定パスを設定
  2. Cursor で /start_ns_session master='[MASTER]office.nsm' を実行（または直接 LLM に指示）
  3. LLM が suggest_workspace → set_workspace を呼び出してワークスペースを確立（未設定時のみ）
  4. LLM が get_workspace_info → get_ai_context で現状を把握しサマリを報告
    • マスタが存在しなければ create_empty_master(filename='[MASTER]office.nsm') で作成、または既存 .xlsx を import_master で変換
  5. LLM へ「Core-SW を追加して Vlan 10 SVI に VLAN10 を割り当てて」のように指示
  6. LLM が run_commands で複数コマンドを発行
  7. export_diagram で L1 / L2 / L3 図を生成
  8. Excel で開きたい場合は export_master_xlsx('[MASTER]office.nsm') を呼び出す

既存 .xlsx マスタの移行 (Local MCP)

Local MCP セットアップ前に作成した .xlsx マスタは以下の手順でインポートできます：

# 1. ワークスペースを確立（未設定時のみ）
suggest_workspace()
set_workspace('~/Documents/ns_workspace')

# 2. 絶対パスで既存マスタをインポート
import_master(
    xlsx_path = '/path/to/[MASTER]office100_v2.xlsx',   # OS に応じた絶対パス
    target_name = '[MASTER]office100_v2.nsm'             # 任意
)

# 3. 元の .xlsx は手動で削除可能（run_commands では使用不可）

安全機構 (Local MCP)

  • ワークスペース境界： set_workspace(path) は Path.home() 配下のパスしか受け付けず、ホストシステムへの意図しないアクセスを防ぐ
  • マスタパス検証： 作業ディレクトリ外のファイルへのアクセスは拒否、.nsm 拡張子は必須
  • run_commands の allowlist： 許可されるのは add / rename / delete / show のみ、export は専用 Tool 経由
  • --accept-security-risk 自動付与： get_ai_context が input() でブロックするのを防止
  • --master 自動付与： 内部で付与するため、LLM が誤って外部マスタを対象にできない
  • import_master / export_master_xlsx の出力先： 常に作業ディレクトリに固定
  • 既存ファイルの上書き禁止： create_empty_master、import_master、export_master_xlsx はいずれも、出力パスが既に存在する場合エラーで停止

アーキテクチャ (Local MCP)

+-----------------------+   stdio (JSON-RPC)   +----------------------+
| Cursor / Claude Code  | <------------------> | ns_mcp_server.py     |
| (MCP host)            |                      | (FastMCP)            |
+-----------------------+                      +----------+-----------+
                                                          | sys.path insert
                                                          v
                                          +----------------------------+
                                          | network-sketcher_online/   |
                                          |   ns_engine/               |
                                          |     nsm_adapter.run_cli()  |
                                          |     nsm_cli.ns_cli_run()   |
                                          |     ...                    |
                                          +-------------+--------------+
                                                        | file I/O
                                                        v
                                          +----------------------------+
                                          | <workspace>/               |
                                          | (set by set_workspace,     |
                                          |  always under user home)   |
                                          |   [MASTER]*.nsm            |
                                          |   [AI_Context]*.txt        |
                                          |   [Lx_DIAGRAM]*.svg/pptx   |
                                          +----------------------------+

トラブルシューティング (Local MCP)

Symptom Cause / Resolution
起動時に [FATAL] ns_engine directory not found network-sketcher_online/ フォルダがありません。本フォルダと同じ親ディレクトリに配置してください。
[FATAL] The "mcp" package is not installed python -m pip install -r requirements_mcp.txt を実行してください。
Cursor の MCP パネルにサーバが現れない mcp.json のパスが正しいか、command に Python 実行ファイル（または仮想環境の Python）が指定されているかを確認してください。
get_ai_context が [ERROR] AI Context file was not generated を返す マスタファイル名が [MASTER] で始まり .nsm で終わっていることを確認してください。
Invalid master filename ... Must start with '[MASTER]' and end with .nsm 本エディションは .nsm 専用です。.xlsx を持っている場合は import_master で変換してください。
[ERROR] No workspace is active for this session suggest_workspace() で候補を確認し、set_workspace(path) でアクティブ化してください。
[ERROR] For safety, the workspace must be under your home directory home ディレクトリ配下のパスのみ受け付けます。home 外を参照したい場合はシンボリックリンクを利用してください。
run_commands が [ERROR] Verb 'export' is not allowed を返す run_commands は export を受け付けません。export_diagram または get_ai_context を使用してください。

Claude Code 固有の環境変数

以下の環境変数は Claude Code でのみ認識されます（Cursor では未使用）。低速な PC や非常に大規模なネットワークで Local MCP を Claude Code 配下で動かす際に有用です。

Variable Purpose
MCP_TIMEOUT=30000 Claude Code の MCP サーバ起動タイムアウトを 30 秒へ延長。既定は約 10 秒で、低速ディスク上での pandas / pyarrow / networkx の初回 import 時に超過することがあります。
MAX_MCP_OUTPUT_TOKENS=50000 Claude Code の Tool あたり出力警告閾値を引き上げ。既定は 10,000 トークンで、大規模マスタに対する get_ai_context は正当に超過し得ます。

Claude Code 起動時に設定する例：

MCP_TIMEOUT=30000 MAX_MCP_OUTPUT_TOKENS=50000 claude

これらのチューニングは Claude Code MCP docs に記載されています。

関連リンク

Author

  • Yusuke Ogawa - Security Architect, Cisco | CCIE#17583

License

SPDX-License-Identifier: Apache-2.0

Copyright 2023 Cisco Systems, Inc. and its affiliates

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Local MCP Edition

Online Edition

Offline Edition

Clone this wiki locally