MCPWiki

English | 日本語

LLM / MCP から使うことを前提にした、軽量なサーバーレス Wiki です。

• 人は Web 画面、LLM は MCP、スクリプトは CLI / REST API から、同じ権限モデルで閲覧・投稿・編集・検索・一覧ができます。

• 記事は GitHub 互換の Markdown (GFM) に OKF (Open Knowledge Format) v0.2 の frontmatter を付けた形で保存します。そのまま OKF バンドルとして入出力できます。

• 記事間のリンクとタグからナレッジグラフを作り、MCP (get_graph, get_backlinks) に提供します。

• AWS のサーバーレス構成（常時課金リソースなし）で、MFA 必須、最小権限、多層防御を前提に設計しています。CI/CD には継続的なセキュリティレビューを組み込んでいます。

アーキテクチャ

検索は OpenSearch を使わず、DynamoDB に置いた自前の転置インデックス（日本語は文字 bigram、英数字は単語単位）で行います。グラフも Neptune を使わず DynamoDB で持ちます。どちらもコストを抑えるための選択です。

外部依存

実行時に使う外部ライブラリは marked（Markdown の描画）と DOMPurify（XSS 対策）の 2 つだけです。YAML (frontmatter) パーサ、JWT 検証、ZIP 入出力、MCP サーバ、CLI は Node 標準機能で自作しています。npm run lint で、許可した依存以外が入っていないことを検査します。

Related MCP server: wikijs-mcp-google-auth

権限モデル

記事ごとに「閲覧範囲」と「編集範囲」を設定します。判定は src/shared/permissions.ts の 1 か所で行い、API、MCP、画面のすべてがこれを使います。

• 管理者は常に閲覧・編集できます。閲覧者 (viewer) はどの記事も編集できません。新規作成は投稿者 (editor) 以上ができます。編集範囲を閲覧範囲より広くすることはできません。

• 閲覧できない記事は、一覧・検索・タグ・グラフ・バックリンク・履歴のどこにも現れず、直接アクセスしても 404 になります。検索のスコアや一覧のカーソルからも存在が推測できないようにしています。

• 過去の版は、その版を書いたときの閲覧範囲でも判定します（範囲を広げても、以前の秘密の版は見えません）。

• 削除は Web 画面からのみ行えます（論理削除で、管理者は復元できます）。MCP と CLI には削除機能がなく、サーバー側でも Web 用クライアントのトークン以外からの削除を拒否します。

• 権限を広げられるのは Web 画面からだけです。 CLI / MCP / API のトークンでは狭めることしかできません。シェルを使えるエージェントがプロンプトインジェクションを受けても、記事を公開されないようにするためです。

• 編集は楽観ロックです（version が一致しなければ 409）。

画面とヘルプページ

• 画面の左に常にサイドバーがあります（ナビゲーション、ヘルプ、最近の更新、タグ）。幅の狭い画面では ☰ で開閉します。

• 初回起動時に、ヘルプ記事 help-wiki（MCPWiki の使い方）と help-markdown（Markdown の書き方）を自動で作成します。全員が閲覧でき、編集できるのは管理者だけです。だれも編集していない間は、原稿の更新がデプロイ後に反映されます。管理者が編集または削除した記事は、そのまま残します（再作成も上書きもしません）。原稿は src/backend/seed/*.md で、変更後は node scripts/gen-seed.mjs を実行します（lint が生成物の更新漏れを検査します）。

• 画面の下のフッターに、MCPWiki のバージョン（リリースではタグ名、それ以外は git describe の結果）と GitHub へのリンクを表示します。

管理者の機能

• サイトタイトル: 「管理 → サイト設定」で変更できます（60 文字まで）。ヘッダー、ブラウザのタブ、エクスポートの index.md に使われます。サインイン前の画面は「MCPWiki」のままです。

• 全記事の一括ダウンロード: 「管理 → OKF 入出力」の「全記事を ZIP でダウンロード」で、公開中のすべての記事（閲覧範囲を問わず、削除済みは除く）を OKF バンドル（index.md と、frontmatter 付きの wiki/<id>.md）としてダウンロードします。そのままインポートできます。添付ファイルは含みません。ZIP は S3 の exports/ に作られ、有効期限 5 分の署名付き URL で渡されます。ファイルは 1 日後に自動で削除されます。Web 画面の管理者だけが使えます（CLI / MCP からは使えません）。監査ログに export-all として記録されます。

添付ファイル（画像・PDF）

• 対応形式は PNG、JPEG、GIF、WebP、PDF で、1 ファイル 10MB まで、1 記事 100 ファイルまでです。SVG と HTML はスクリプトを含められるため受け付けません。

• 編集画面の「画像・PDF を添付」ボタン、ドラッグ＆ドロップ、貼り付けで添付すると、![名前](/wiki/<記事ID>/files/<ファイルID>) がカーソル位置に挿入されます。PDF はリンク形式になります。

• アクセス権は記事に従います。 閲覧するには記事の閲覧権限が、添付と削除には編集権限が必要です。非公開の記事の添付は、URL を知っていても見られません。

• ファイルは Lambda を経由せず、有効期限 5 分の署名付き URL で S3 と直接やり取りします。署名の際に、保存先の場所、形式、サイズを固定します。アップロード後には、サーバーがファイル先頭のバイト列で形式を確認し、一致しなければ破棄します。画像はページ内に表示し、PDF は常にダウンロードとして扱います。

• 削除は Web 画面からのみ行えます。S3 のバージョン管理により、管理者は復元できます。

• CLI: mcpwiki attach <id> <ファイル>、mcpwiki attachments <id>、mcpwiki download <id> <ファイルID>。MCP: list_attachments、get_attachment（3MB までの画像を LLM に渡します）。MCP からはアップロードできません。

セットアップ

自分の AWS アカウントへの構築から、GitHub Actions による自動デプロイまでの手順は docs/deploy.md にまとめています（前提、fork で書き換える値、初回デプロイ、最初の管理者、CI の設定、prod のリリース、トラブルシューティング、撤去）。

概要:

npm ci --ignore-scripts && npm test && npm run lint
npx cdk bootstrap aws://<account>/<region> aws://<account>/us-east-1   # prod 用の bootstrap
npx cdk deploy MCPWiki-guard && node scripts/bootstrap-dev.mjs         # 共有アカウントの境界と dev 専用の bootstrap
npm run deploy:dev                                                     # dev（独自ドメインは config/domains.local.json）
scripts/create-admin.sh dev <username> <email> admin                   # 最初の管理者を招待

以降は、main へのマージで dev に、v* タグの push（承認 2 回）で prod にデプロイします。

CI/CD とセキュリティレビュー

Private リポジトリで運用する場合: Code scanning（SARIF のアップロード）、Dependency Review、Secret scanning は、GitHub の有償機能（GitHub Code Security / Secret Protection）が必要です。既定ではこれらを使わず、各スキャナは指摘があればジョブを失敗させ、レポートを artifact に残します（CodeQL も同じ）。Public にする、または有償機能を契約したら、リポジトリ変数 CODE_SCANNING_ENABLED=true を設定すると、結果が GitHub の Security タブ（Code scanning）に集約されます。Rulesets によるブランチ保護と、Environment の Required reviewers も、Private ではプランによって使えないことがあります。

アクションはすべてコミット SHA で固定し、Dependabot が更新します。

GitHub 側の初期設定（OIDC、シークレット、Environments）と、公開リポジトリにする場合の保護設定（Rulesets、タグ保護、fork の PR）は docs/deploy.md を参照してください。Issue と PR は誰でも作成できます。マージは、書き込み権限を持つ人（メンテナ）だけが行えます。貢献の手順は CONTRIBUTING.md を参照してください。

CLI

npm run build
install -m 755 dist/cli/mcpwiki.mjs ~/.local/bin/mcpwiki     # 依存なしの単一ファイル

mcpwiki configure --env dev --url https://wiki-dev.example.com
mcpwiki login                     # ブラウザで MFA 付きサインイン (PKCE)
mcpwiki list --tag aws
mcpwiki search 東京タワー
mcpwiki get <id>                  # OKF 文書（frontmatter + Markdown）を出力
mcpwiki create --title "手順書" --tags ops,aws --file doc.md
mcpwiki edit <id>                 # $EDITOR で OKF 文書を編集（楽観ロック付き）
mcpwiki graph <id> --depth 2 --tags
mcpwiki export --out bundle.zip   # 自分が読める記事の OKF バンドル
mcpwiki attach <id> shot.png      # 添付（表示された Markdown を本文に貼る）
mcpwiki attachments <id>          # 添付の一覧
mcpwiki download <id> <ファイルID> # 添付の保存

ブラウザが別のマシンにある場合は、サインイン後に表示される http://localhost:53682/callback?... の URL を CLI に貼り付けてください。トークンは ~/.config/mcpwiki/credentials.json（0600）に保存し、自動で更新します。

Windows

CLI と MCP ブリッジは Windows でもそのまま動きます（npm test の E2E も Windows で通ります）。前提は Node.js 20 以上と Git です。

git clone https://github.com/siseru/mcpwiki.git
cd mcpwiki
npm ci --ignore-scripts
npm run build
npm install -g .                  :: mcpwiki コマンド（npm が mcpwiki.cmd を作ります）
mcpwiki configure --env dev --url https://wiki-dev.example.com
mcpwiki login

インストールせずに node dist\cli\mcpwiki.mjs <command> と直接呼んでも同じです。Windows では次の点が異なります。

• 設定とトークンは %APPDATA%\mcpwiki\（XDG_CONFIG_HOME があればそちら）に保存します。POSIX の 0600 に相当する保護はなく、ユーザープロファイルの ACL に従います。

• mcpwiki login は rundll32.exe url.dll,FileProtocolHandler 経由で既定のブラウザを開きます（--no-browser で URL を手で開くこともできます）。

• mcpwiki edit <id> の既定のエディタは notepad.exe です。VISUAL / EDITOR を設定する場合、空白を含むパスは引用符で囲みます（例: set EDITOR="C:\Program Files\Notepad++\notepad++.exe" -multiInst）。code --wait のような .cmd のラッパも使えます。エディタは閉じるまで待つものを指定してください。

• --file に渡す Markdown は CRLF でも BOM 付きでも構いません（読み込み時に正規化します）。

• npm run build / npm test / npm run lint / npm run typecheck / npm run synth は cmd / PowerShell でも動きます（CI も windows-latest で lint・typecheck・テストを実行します）。bash が必要なのはデプロイ用の scripts/create-admin.sh だけです（Git Bash か WSL で実行してください）。

MCP

MCP クライアントからは、CLI に組み込まれた stdio ブリッジ（mcpwiki mcp）を使うのが簡単です。ブリッジは CLI に保存されたログイン情報を使い、トークンの更新も自動で行います。先に CLI でログインしてください（mcpwiki whoami が通る状態）。

mcpwiki configure --env dev --url https://wiki-dev.example.com
mcpwiki login --env dev

Claude Code

claude mcp add --scope user mcpwiki -- mcpwiki mcp --env dev
claude mcp list            # mcpwiki が Connected になっていることを確認

Windows では mcpwiki が mcpwiki.cmd になり、MCP クライアントからは起動できないことがあります。node で .mjs を直接起動してください（パスは clone した場所に合わせます）。

claude mcp add --scope user mcpwiki -- node C:\Users\<user>\mcpwiki\dist\cli\mcpwiki.mjs mcp --env dev

• --scope user を付けると、どのディレクトリで起動しても使えます（リポジトリ単位にしたい場合は --scope project）。

• 登録後に Claude Code を起動し直し、/mcp で接続状態とツールの一覧を確認します。

• 例:「MCPWiki で istus の記事を探して要約して」「今日の作業を MCPWiki に記事としてまとめて。タグは worklog」

Kiro

~/.kiro/settings/mcp.json（全ワークスペース共通）か、ワークスペースの .kiro/settings/mcp.json の mcpServers に追加します。既存のサーバの設定は残してください。

{
  "mcpServers": {
    "mcpwiki": {
      "command": "/usr/bin/node",
      "args": ["/home/<user>/.local/bin/mcpwiki", "mcp", "--env", "dev"],
      "disabled": false,
      "autoApprove": ["list_articles", "get_article", "search_articles", "list_tags", "get_graph", "get_backlinks", "list_attachments", "get_attachment"]
    }
  }
}

• Kiro の起動環境では ~/.local/bin が PATH に入っていないことがあるので、node と mcpwiki は絶対パスで書きます（which node と which mcpwiki で確認できます）。

• Windows では、args に mcpwiki.cmd（where mcpwiki が返すパス）ではなく、clone した場所の dist\cli\mcpwiki.mjs を書きます。node.exe のパスは where node で確認します。JSON ではバックスラッシュを \\ と書きます。

  "command": "C:\\Program Files\\nodejs\\node.exe",
  "args": ["C:\\Users\\<user>\\mcpwiki\\dist\\cli\\mcpwiki.mjs", "mcp", "--env", "dev"],

• autoApprove には読み取り用のツールだけを入れます。作成（create_article）と更新（update_article）は、実行前に Kiro が確認を求めます。

• 保存したら、Kiro パネルの MCP SERVERS で mcpwiki が接続済みになり、10 個のツールが表示されることを確認します（表示されなければ再接続します）。

共通の注意

• MCP から作成した記事は draft として保存されます。内容を確認したら、Web 画面の「レビュー済みにする」で人による確認を記録してください。

• MCP からは削除できず、閲覧・編集範囲を広げることもできません（Web 画面でのみ可能）。

• session expired になったら mcpwiki login を実行し直します（リフレッシュトークンの有効期限は 7 日）。

リモートのエンドポイントは https://<host>/mcp（Streamable HTTP）です。未認証のリクエストには、RFC 9728 の WWW-Authenticate: Bearer resource_metadata=... を付けて 401 を返します。認可サーバは Cognito（PKCE、事前登録クライアント cliClientId、コールバック http://localhost:53682/callback）です。

記事の内容は信頼できないデータとして扱い、応答ごとにランダムな境界タグで区切って返します。

OKF について

---
type: Wiki Article
title: 東京タワーの歴史
description: 1958 年完成の電波塔の概要
tags: [観光, 歴史]
status: stable
generated: { by: "human:taro", at: "2026-10-07T00:00:00.000Z" }
verified:
  - by: "human:hanako"
    at: "2026-10-08T00:00:00.000Z"
mcpwiki: { id: tokyo-tower, owner: taro, read_scope: all, write_scope: owner, version: 3, ... }
---

本文…… [関連記事](/wiki/other-article)

• 記事間のリンクは [表示名](/wiki/<id>) と書きます（/wiki/<id>.md や <id>.md も認識します）。

• generated.by には、Web と CLI の編集なら human:<ユーザ名>、MCP の編集なら mcpwiki-mcp/<version> が入ります。「レビュー済みにする」を押すと verified に追加されます（内容が変わるとリセット）。

• 拡張キーは保持されます。エクスポートされるバンドルは index.md（okf_version: "0.2"）と wiki/<id>.md で構成されます。

コスト目安

小規模（数十ユーザ、数千記事）なら、dev は月数ドルです。prod は WAF（月 9 ドル前後）、WAF のログ、Backup（データ量に比例）を加えて、月 10〜20 ドル程度の見込みです。常時起動のリソースはありません。

すべてのリソースに、コスト配分タグ Project=mcpwiki、Environment=dev|prod（共通のスタックは shared）、Component=app|edge|cicd|guard、ManagedBy=cdk を付けます。Cost Explorer では、Billing の「コスト配分タグ」で有効にしたキーで集計できます（有効化は管理アカウントで一度だけ。タグが付いてから一覧に出るまで最大 24 時間かかります）。タグは -c costTags='{"CostCenter":"…"}' で追加・上書きできます。

ディレクトリ

src/shared   権限、OKF、YAML サブセット、トークン化、入力検証（API / Web / CLI で共通）
src/backend  Lambda: ルーティング、JWT 検証、業務ロジック、MCP、DynamoDB/S3 ストア、ZIP
src/web      SPA（ユーザ画面と管理画面）
src/cli      mcpwiki CLI と MCP stdio ブリッジ
src/infra    CDK: WikiStack / EdgeStack / GuardStack / CiStack
test         node:test（E2E とセキュリティ回帰テストを含む）
scripts      build / lint / smoke / create-admin / bootstrap-dev / diagrams
docs         設計資料と図

セキュリティ設計の詳細: docs/security.md / 脆弱性の報告: SECURITY.md

ライセンス

Apache License 2.0（LICENSE）