Skip to main content
Glama

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 には継続的なセキュリティレビューを組み込んでいます。

アーキテクチャ

MCPWiki runtime architecture

役割

サービス

備考

DNS / 証明書

Route 53 + ACM (us-east-1)

<host> と auth.<host> を 1 枚の証明書でカバーします。DNS 検証なので自動で更新されます。CAA で発行元を Amazon に限定しています

配信

CloudFront + S3 (OAC)

TLS 1.2 以上、CSP / HSTS などを付けます。*.cloudfront.net へのアクセスは正規のホストへリダイレクトします

防御

AWS WAF (prod)

IP レート制限、AWS マネージドルール、ログ出力(認証ヘッダは伏せ字)

認証

Cognito User Pool (Essentials, managed login)

MFA 必須(TOTP、またはパスキー)、招待制、グループ admin / editor / viewer

API / MCP

API Gateway HTTP API + Lambda (Node.js 24, arm64)

1 つの関数で REST と MCP Streamable HTTP を処理します。JWT は Lambda 内で検証します

データ

DynamoDB (on-demand, PITR)

メタデータ、検索の転置インデックス、リンク(グラフ)、履歴、監査ログ、レート制限

本文

S3 (versioning)

articles/<id>.md に OKF 文書を置き、S3 のバージョンが履歴を兼ねます。Lambda には削除権限を与えていません

バックアップ

AWS Backup (prod)

毎日取得して 35 日保持します。ボールトにはロック(最低 7 日)を掛けています

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

外部依存

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

Related MCP server: wikibrain

権限モデル

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

設定

値

閲覧 readScope

admin 管理者のみ / owner オーナー(作成者)のみ / all だれでも(ログインユーザ)

編集 writeScope

none 読み取りのみ / admin 管理者のみ / owner オーナーのみ / all 投稿者全員

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

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

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

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

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

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

画面とヘルプページ

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

  • 一覧、タグ、検索では「自分がオーナーの記事のみ」で絞り込めます(?mine=1。サイドバーの「自分の記事」)。

  • グラフは拡大縮小と移動ができます。丸の大きさはリンクの数で決まり(直径で最大 2 倍)、名前が重なる場合はリンクの多い記事を優先して表示します。

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

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

管理者の機能

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

  • 記事の一括操作: 「管理 → 記事」でチェックボックスを使って記事を選び(絞り込み、表示中のすべてを選択、すべて読み込むが可能)、まとめて「レビュー済みにする」か、閲覧範囲・編集範囲を指定した値に変更します(権限の拡大を含む)。確認画面では、権限が広がる記事の件数を表示します。記事ごとに通常の編集と同じ検査(編集範囲は閲覧範囲より広くできない、など)を行い、履歴と監査ログもそれぞれ残します。失敗した記事は理由とともに一覧表示され、ほかの記事の処理は続きます。Web 画面の管理者だけが使えます。

  • 全記事の一括ダウンロード: 「管理 → 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 とセキュリティレビュー

CI/CD and isolation

ワークフロー

契機

内容

ci.yml

PR / main

lint(依存、XSS、ワークフローの固定)、型検査、テスト(セキュリティ回帰テストを含む)、cdk synth + cdk-nag、npm audit、npm audit signatures

security.yml

PR / main / 毎週

gitleaks(全履歴の秘密情報)、OSV-Scanner(既知の脆弱性と悪性パッケージ)、Dependency Review(PR)、checkov(合成済みテンプレート)、zizmor(Actions の監査)、OWASP ZAP baseline(dev、毎週)、Claude による AI レビュー(任意)

supply-chain.yml

依存を変更する PR

lockfile の審査(公開から 7 日未満・インストールスクリプトの追加・provenance の欠落・レジストリ以外からの取得を拒否。公開者の変更と新規の依存は警告。実行時の依存の差分を保存)、インフラ差分(変更前後で synth して比較し、依存だけの PR でセキュリティに関わるリソースが変われば停止)

codeql.yml

PR / main / 毎週

CodeQL(security-extended、TypeScript と GitHub Actions)

scorecard.yml

main / 毎週

OpenSSF Scorecard

deploy.yml

main → dev、v* タグ → prod

認証情報を持たないジョブで build/synth し、デプロイするジョブだけが OIDC トークンを得ます(npm ci --ignore-scripts、キャッシュなし)

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)です。

ツール

内容

list_articles / get_article / search_articles

一覧、OKF 文書の取得(過去の版も可)、全文検索

create_article / update_article

作成(既定は status: draft)、部分更新(version 必須、権限は狭めるだけ)

list_tags / get_graph / get_backlinks

タグ、関連グラフ(link は有向、tag は共通タグ)、被リンク

list_attachments / get_attachment

添付の一覧、画像の取得(3MB まで。PDF はメタデータのみ)

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

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 / 別のスタックで作る画面を足す(拡張、既定は OFF): docs/extensions.md

ライセンス

Apache License 2.0(LICENSE)

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to maintain a persistent Markdown knowledge base by ingesting sources, searching and reading notes, and creating or updating wiki pages with optimistic locking.
      13
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides OAuth-secured MCP tools for working with private, Git-backed Markdown knowledge bases: searching pages, reading content, ingesting new source documents, retrieving cited original files, and reviewing history or rolling back accepted pages. Every tool call is checked against each person's or agent's current wiki grant and returns source paths and Git revisions for traceability.
      MIT