mcpField
H
Hatchdoor

Hatchdoor

ローカル
docs-hatchdoor.battercloud.cc生産性681 日前に更新

Hatchdoor について

Hatchdoor は、Markdown のノート保管庫をセルフホストするサービスで、Web UI と AI エージェントが同じノートにアクセスできます。Obsidian やプラグインなしでディスク上のファイルを読み込み、アトミック書き込みと楽観的同時実行制御で編集を保護します。

主な機能

  1. 01Markdown ノートの閲覧と編集
  2. 021 つのインスタンスで複数保管庫を管理
  3. 03キーワード検索とセマンティック検索
  4. 04ウィキリンク、バックリンク、グラフ表示
  5. 05MCP によるノートと添付ファイルの操作
  6. 06任意の Git 自動コミットとプッシュ

活用シーン

  1. 01ブラウザーでローカルの Markdown 保管庫を管理
  2. 02エージェントによるノートの検索、作成、編集、リンク
  3. 03複数の保管庫にまたがるノートアクセスを提供
  4. 04変更元を示す Git コミットとして変更を記録

MCP 対応

Hatchdoor は MCP サーバーを内蔵し、エージェントが指定した保管庫内のノートを読み取り、検索、作成、編集、移動、リンクできます。書き込みには Web UI と共通のアトミック操作を使い、楽観的同時実行制御に対応します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"batterworks-hatchdoor": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/battermanz/hatchdoor:2.8.1"
]
}
}
}
起動コマンドdocker run -i --rm docker.io/battermanz/hatchdoor:2.8.1

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
ocidocker.io/battermanz/hatchdoor:2.8.1

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

Hatchdoor

ライブデモ ドキュメント Docker Hub rootless および distroless イメージ ライセンス:AGPL-3.0

Hatchdoor

Obsidian の保管庫をセルフホストできます。ウェブ UI はあなた向け、MCP は AI エージェント向けです。 Obsidian もプラグインも必要ありません。

Hatchdoor は保管庫をディスクから直接読み込みます。Markdown ノートが入ったフォルダーなら、どれでも使えます。Local REST API プラグインも、起動したままにするデスクトップアプリも必要ありません。高速なウェブ UI でノートの閲覧、検索、編集ができ、Claude、Claude Code、Codex、Cursor、Hermes などの Model Context Protocol(MCP)クライアントを同じ保管庫に接続すれば、エージェントによるノートの読み取り、検索(キーワード検索とセマンティック検索)、作成、編集、移動、リンクが可能になります。1 つのサーバーで任意の数の保管庫を管理でき、すべての書き込みは UI と同じアトミックな保管庫操作を通じて行われます。楽観的並行性制御に対応し、必要に応じて git の自動コミットとプッシュも利用できます。ウェブ UI とエージェントは、1 つの保管庫にアクセスする 2 つの窓口です。

Markdown ファイルが常に信頼できる情報源です。Hatchdoor は、高速な閲覧、リンク、バックリンク、キーワード検索、セマンティック検索、グラフデータ、メタデータのために、破棄可能な SQLite 読み取りモデルを構築します。キャッシュを削除しても、Hatchdoor は保管庫から再構築します。

Hatchdoor は、主に Claude Code と Codex などの AI コーディングエージェントを活用し、綿密な人間によるレビュー、テスト、文書化された安全性モデルのもとで開発されました。

Hatchdoor でノートを編集中:左側に保管庫エクスプローラー、中央に選択した語句の上へ書式設定ツールバーが表示されたライブエディター、右側にページ内アウトライン

▶  ライブデモを試す(読み取り専用の公開保管庫)か、 セットアップと使い方のガイドについてはユーザードキュメントをご覧ください。

目次
## 提供される機能
  • フォルダーや Markdown ノートを閲覧できる Web UI。
  • ネイティブな複数 Vault 対応:1 つのインスタンスで複数の Vault を提供し、それぞれが独自のソース、Git 同期、エージェントの適用範囲を持ちます。
  • /v/<vault-id>/n/<slug> のわかりやすいノート URL。
  • [[Note]]、[[Folder/Note]]、[[Note|Alias]] に対応した Obsidian 形式の Wiki リンクと、.md ファイルへの Markdown リンクに対応し、どちらも名前変更や移動に応じて最新の状態に保たれます。新しいリンクには、各 Vault 固有のリンクスタイルが適用されます。
  • 保存済みクエリ:Obsidian の Bases 構文を使ったフェンス付き base ブロックで、該当するノートをリアルタイムのテーブルに表示できます。人にもエージェントにも利用できます。
  • GitHub Flavored Markdown、数式、Mermaid 図、フロントマター、画像、添付ファイル、リンク切れのスタイルに対応した Markdown レンダリング。
  • キーワード検索とセマンティック検索。
  • 最近のノート、バックリンク、外部リンク、統計、グラフ表示。
  • Vault のマウント先が書き込み可能な場合に使える、ブラウザー上のライブエディター。ノートを開くとすぐに入力でき、Markdown 構文は編集中の行にだけ表示され、編集内容は自動で保存されます。Obsidian のライブプレビューと同じように動作します。
  • 添付ファイルのアップロード、ローカルアセットの配信、リンクされた PDF Vault アセットのインラインプレビュー。
  • AI エージェントが UI と同等の安全性でノートの読み取り、検索、作成、編集、リンクを行える、第一級の MCP サーバー。Vault 全体のタグを検証付きの 1 回の操作で名前変更または削除でき、サイズを問わない添付ファイルも、有効期間の短いダウンロードリンクとアップロードリンクを通じて移動できます。
  • コンテキストウィンドウに合わせたエージェント向けの読み取り機能:コンパクトな検索結果、長いノートのアウトラインと指定されたセクションのみの取得、すべての出現箇所を数える完全一致検索。
  • 新規インストール時に、空のインスタンスからエージェントがノートを検索できる状態まで案内するセットアップチェックリスト。コンテナーパスの代わりにフォルダーピッカーを使用します。
  • アプリに組み込まれたマニュアル:作業中の画面からヘルプを参照でき、エージェントは read_docs と search_docs で同じページを利用できます。また、すべてのインスタンスで /docs/ にプレーンな Markdown として公開されます。
  • Hatchdoor による書き込み時の Git コミットとプッシュを任意で自動化できます。各コミットには変更元(Web UI、名前付きエージェント、外部編集)が記録され、同期の競合はリカバリーブランチを通じて Git ホスト上で解決されます。
  • 一般的な読み取りパス向けの PWA アセットとサービスワーカーのキャッシュ。
  • シェルを含まず、nonroot として実行する、Distroless かつルートレスのコンテナーイメージ。Docker または Podman でデプロイできます。

スクリーンショット

ノート、リンク、タグのインタラクティブなナレッジグラフ

ナレッジグラフ:ノート、リンク、タグ

自然言語クエリに対するスニペット付き検索結果

セマンティック検索+キーワード検索

ダークモードでレンダリングされたノート表示

ダークモード

スマートフォンでのレスポンシブなモバイルレイアウト

レスポンシブ対応・インストール可能(PWA)

対象ユーザー

Hatchdoor は、Markdown ノートを保存したフォルダーがあり、それを閲覧するためのプライベートな Web インターフェースが欲しい場合に便利です。

Docker Compose で簡単に実行できるため、初心者にも使いやすい一方、エージェントアクセス、Git 管理の Vault 同期、セマンティック検索、ローカル開発を求める方向けの高度な機能も備えています。

Hatchdoor は、ホスト型の同期サービスでも、複数ユーザー向けのコラボレーションプラットフォームでも、Obsidian の代替品でもありません。自分で管理する Markdown Vault のための、セルフホスト可能なコンパニオンです。

Hatchdoorの比較

MCP for Obsidianの分野には多くのツールがあります。率直に言うと、Obsidianアプリ内で作業し、できるだけシンプルな連携を求めているなら、プラグインベースのツールで十分です。Hatchdoorは、Obsidianとは独立してボルトを提供したい場合に向いています。ホームラボのマシンから、ブラウザーとエージェントの両方に、複数のボルトを提供できます。

Hatchdoormcp-obsidianLocal REST APIBasic MemoryOpenKnowledge
概要セルフホスト可能なボルトサーバー:ウェブ UI + MCPREST プラグインへの MCP ブリッジREST プラグインそのものローカルの Markdown 上の AI メモリ。MCP を最優先AI 機能を備えた WYSIWYG Markdown エディター
Obsidian をインストールせずに動作✅ ディスク上のボルトを読み込みます❌ Obsidian とプラグインの実行が必要です❌ Obsidian 内で動作します✅✅ 独自のエディター
人間向けウェブ UI✅ セルフホスト可能、ライブデモ❌❌有料のクラウドアプリ✅ デスクトップアプリ + ローカルウェブアプリ
複数のボルトを提供✅ 1 台のサーバーで、ボルトごとに Git 同期❌❌✅ プロジェクト❌ インスタンスごとに 1 つのフォルダー
エージェントによる編集の書き込み安全性アトミックな書き込み、楽観的同時実行制御プラグインの REST API 経由—上書き防止機能—
サービスとしてデプロイ✅ Docker/Podman、rootless、トークン認証❌ デスクトップに依存❌❌ ローカルプロセス(クラウド版は有料)❌ ローカル CLI アプリ

Basic Memory と OpenKnowledge は、隣接する課題(エージェントメモリ、AI ネイティブなエディター)を解決する優れたプロジェクトです。Hatchdoor が重なるのは、ノートが提供対象のボルトである場合に限られます。つまり、ブラウザーとエージェントの両方に提供できる、常時稼働の単一サービスです。

今後の予定

次の大きな機能は、権限範囲を設定できる複数アカウントへの対応です。現在、Hatchdoor はプライベート環境で信頼できるユーザーが 1 人だけいることを前提としているため、インスタンスにアクセスできる人は誰でも、提供されているすべてのボルトを閲覧できます。今後は、複数の人やエージェントが 1 つのインスタンスを共有し、それぞれに許可されたボルトだけを割り当てるとともに、管理者ロールでその他の設定を管理できるようにする予定です。これにより、家庭や小規模チームで、1 人につき 1 台ではなく、Hatchdoor を 1 台だけ運用できるようになります。

v2.5.0 ではすでに、ボルトが製品によって管理される独立したアドレス指定可能な対象となり、MCP エージェント向けのボルト範囲設定にも対応しました。まだ実装されていないのは、意図的に後回しにした残りの半分、つまりアカウント、認証、そして UI が示唆するだけではなくサーバーが強制するアクセス境界です。v3 を目標としています。

ほかにも実現したいことが 2 つありますが、対応するバージョンはまだ決まっていません。

  • エージェントの出所情報と取り消し。 どのエージェントがノートを変更したのか、作成されたコミットに添えられた変更前後の差分、ワンクリックでの取り消しです。現在は Git がすべてを担っています。各コミットには変更したエージェント名が記録されますが、コミットログを読むことと、エージェントがノートに加えた変更を確認することは同じではありません。
  • ボルトの整合性チェック。 孤立したノート、壊れた Wiki リンク、宣言が失われたレイヤーマーカーを検出する、ボルト単位の lint 機能です。エージェントが無人で管理するボルトの構造が、気づかないうちに崩れてしまうのを防ぎます。

製品ロードマップに、すべての作業項目と各項目の進捗状況を記載しています。

Docker ですぐに始める

Claude Code や Codex のように、ターミナルを使える AI エージェントをお持ちですか?次の 1 行を渡せば、いくつかの質問に答えるだけで Hatchdoor をインストールできます。

Read https://hatchdoor.battercloud.cc/docs/deploy.md and install Hatchdoor for me.

手動で行う場合は、以下の手順に従ってください。

1. 必要なもの

以下が必要です。

  • Docker と Docker Compose(Podman と podman compose も使用できます)
  • Markdown ボルトのフォルダー。最初から始める場合は空のフォルダーでもかまいません
2. 設定を作成する

サンプルの環境ファイルをコピーします。

cp .env.example .env

デフォルトでは、Compose ファイルと同じ場所にある空の vault フォルダーがマウントされます。既存の Vault を使うには、.env でホスト側のパスのコメントを外します。

HOST_VAULT_PATH=/absolute/path/to/your/markdown-vault

各項目の意味は次のとおりです。

  • HOST_VAULT_PATH は、ホストマシン上の Markdown Vault です。
  • HOST_CACHE_PATH、HOST_STATE_PATH、HOST_MODELS_PATH は省略可能なホスト側の保存先です。それぞれ、生成されたキャッシュ、正規の Vault レジストリ、ダウンロードしたモデルに使用します。Compose では、プロジェクトと同じ場所に保存されるよう設定されています。

マネージド Vault を初めて起動する前に、イメージの数値 nonroot ユーザーがアクセスできるよう、デフォルトの正規状態ディレクトリを作成してください。Docker は、存在しないバインド元を root として作成することがあり、その場合レジストリに書き込めなくなります。

mkdir -p data/state
chmod 700 data/state
sudo chown 65532:65532 data/state

rootless Podman の場合は、sudo chown の代わりに podman unshare chown 65532:65532 data/state を使ってください。カスタムの HOST_STATE_PATH にも同じ所有権ルールを適用してください。

通常の Settings の値を .env に追加しないでください。値が設定されていなければ、Settings で実行中に変更できます。常に環境変数のみで設定する必要があるデプロイ値については、設定を参照してください。

3. Hatchdoor を起動する
docker compose up -d

Docker Compose は Hatchdoor をコンテナーの非ループバックインターフェースにバインドするため、Web トークンなしで初回起動すると、安全のため停止し、新しい再取得可能なトークンを表示します。次のコマンドで取得してください。

docker compose logs hatchdoor

表示された HATCHDOOR_WEB_BEARER_TOKEN=... の代入文を .env にコピーし、docker compose up -d で再度起動します。このトークンは Hatchdoor に保存されません。起動を拒否した際に表示されたものを使うか、新しい長いランダムトークンを生成してください。サーバーが起動したら、http://localhost:42824 を開き、ブラウザーのプロンプトにトークンを入力します。

4. 検索モデルを選ぶ

Hatchdoor のイメージにはモデルの重みは含まれていません。初回起動時に、何かをダウンロードする前に、Hatchdoor がモデルを選ぶよう求めます。選択肢は、Gemma(多言語対応。利用規約への同意が必要なため推奨)または Nomic Embed Text v1.5(英語のみ。利用規約への同意は不要)です。いずれの場合も、モデルと同意の記録は HOST_MODELS_PATH に保存され、再起動後も保持されます。Hatchdoor が Vault の内容を外部に送信することはありません。セットアップが完了するまで、Vault の機能は利用できません。

新規インストール時には Vault がありません。モデルの準備が整うと、Set up Hatchdoor のチェックリストが開きます。ノートフォルダーを Vault として追加し、エージェントを接続して、検索を試してください。トップバーの ? ボタンを押すと、実行中のバージョンのマニュアルである Help が開きます。

5. コンテナーイメージとパス

イメージは Docker Hub で公開されています。

battermanz/hatchdoor:latest          # also version tags, e.g. 2.9.0
battermanz/hatchdoor:podman-latest   # for Podman users (podman-<version> too)

実行時イメージは distroless かつ rootless です。gcr.io/distroless/cc-debian13:nonroot をベースにビルドされており、シェルやパッケージマネージャーは含まず、権限のない nonroot ユーザーとして実行されます。Hatchdoor は Podman(rootless を含む)でも変更なしで動作します。docker/docker compose を podman/podman compose に置き換え、さらにイメージタグも podman-latest(または podman-<version>)に置き換えてください。上記の latest タグは Docker 専用です。

Docker Compose では次のパスがマウントされます。

コンテナーパス用途
/data/vaultMarkdown Vault、正本
/data/cache生成された SQLite キャッシュ
/data/state正規の Vault ID とソース定義
/modelsダウンロードした検索モデルと、ローカルに保存された Gemma の利用規約への同意記録

データと安全性に関するモデル

Hatchdoor は、シンプルなルールを軸に設計されています。Markdown ボルトが信頼できる情報源です。

  • Markdown ファイルは、ボルトレジストリに記録された各ボルト専用のフォルダーに保存されます。VAULT_PATH はその場所ではありません。Hatchdoor が認識できるフォルダーであり、ボルトを追加するまでは、その中のどのフォルダーもボルトにはなりません。新規インストール時にはボルトはありません。
  • ボルトの識別情報とソース定義は /data/state/vaults.json に保存されます。ボルトの Git HTTPS 認証情報もここに保存されるため、このファイルは Unix では権限 0600 で作成され、機密情報として扱うバックアップに含める必要があります。API が認証情報を返すことはありません。ボルトが返すのは credential_configured のみです。また、保存済みのシークレットを維持する編集では再送信する代わりに、https_credentials: {"action": "keep"} を指定します。
  • SQLite は生成されるキャッシュであり、再構築できます。
  • SQLite キャッシュはボルトの外部に配置してください。
  • Hatchdoor は、組み込みおよび設定済みの除外対象パス(.hatchdoor-trash を含む)を除外しながら、ボルト内の .md ファイルをスキャンします。
  • 削除操作では、ノートと、それぞれのフォルダー内に保存されているアセットが .hatchdoor-trash に移動されます。
  • アーカイブ操作では、ノートが HATCHDOOR_ARCHIVE_PREFIX の下に移動されます。
  • ブラウザーからの書き込み操作は、ボルトが書き込み可能な場合にのみ利用できます。
  • MCP はデフォルトで無効です。
  • MCP を有効にする場合は、専用のベアラートークンが必要です。
  • バージョン管理はデフォルトで無効です。有効にすると、ローカルの Git 履歴を保持するか、既存のリモートと安全に同期できます。

2.4.x 以前の単一ボルト構成は、このバージョンに直接アップグレードできません。まず 2.5.0 から 2.7.x のリリースにアップグレードしてください。これにより、ボルトがレジストリに移行されます。このようなインストールでは、空の状態で開くのを避けるため、Hatchdoor は起動を拒否します。旧式の単一ボルトからのアップグレードガイドを参照してください。

Hatchdoor がボルトフォルダーにサンプルノートを書き込むことはありません。空のフォルダーは、Markdown ファイルを追加するまで空のボルトとして開きます。

書き込みアクセスについては、ブラウザーからの書き込み、MCP からの書き込み、添付ファイルのアップロード、Git 同期のいずれにも、ボルトのマウント、キャッシュディレクトリ、状態ディレクトリが、コンテナー内の非 root 実行ユーザーによって書き込み可能である必要があります。キャッシュディレクトリと状態ディレクトリが書き込み可能なままであれば、ボルトが読み取り専用でマウントされていても、読み取り専用の閲覧は可能です。書き込み機能が予期せず無効になっている場合は、これらのマウント権限を確認してください。

Hatchdoor は、PARA、Zettelkasten、Andrej Karpathy の LLM wiki パターン、またはそのいずれでもない構成など、特定のボルトのレイアウトを要求しません。ユーザードキュメントではそれぞれを比較しており、Hatchdoor で LLM wiki を実行する方法では、レイヤーベースのセットアップ(生のソースを別の .hatchdoor-layer に置き、キュレーション済み wiki のデフォルトの表示領域を設定する方法)を順に説明しています。

設定

.env.example を .env にコピーします。値はすべてコメントアウトされています。通常のデフォルト値は Docker Compose と Hatchdoor が提供し、サーバーの実行中の設定は Settings が管理します。サーバー全体に適用される Settings キーに .env で空でない値を指定すると、意図的な 環境ピン となります。この値はそのプロセスで保存済みの Settings 値より優先され、ピンを削除してコンテナーを再起動するまで、Settings には .env で設定 と表示されます。Vault の定義は .env ではなく、Settings、HTTP API、または MCP を通じて Vault ごとに管理します。

デプロイ前に知っておきたいデフォルトが 2 つあります。

  • HATCHDOOR_WEB_BEARER_TOKEN が設定されていない場合、Hatchdoor は HOST=0.0.0.0 やその他のループバック以外のアドレスへのバインドでの起動を拒否します。拒否されると、新しいトークンと追加すべき .env の行が表示されます。これは不具合ではなく、解決方法です。
  • HATCHDOOR_DEMO_MODE=true にすると、認証なしの読み取り専用インスタンスが実行され、一般公開用の閲覧に利用できます。このモードには独自のレート制限がありません(検索ではすべてのクエリを埋め込み処理し、ノートのダウンロードでは添付ファイルをメモリ上にまとめます)。そのため、一般公開する前に、レート制限を行うリバースプロキシを前段に設置してください。

オプション設定のうち 1 つは、意図的に .env.example から除外されています。 HATCHDOOR_USAGE_REPORT_ENABLED です。これはテレメトリーであり、Settings の Usage report で有効にするか、.env で true に設定しない限りオフです。有効にすると、Hatchdoor はインストール環境の構成に関する小さなレポートを 1 日に 1 回、メンテナーに送信します。ノートに関する情報は送信されません。これは、どのプラットフォームをテストするか、また Hatchdoor のどの機能が利用されているかを判断するためです。使用状況レポートの リファレンス には、すべてのフィールドが記載されています。

すべてのデプロイ用変数、実行中に Settings で編集できるすべての値、レイヤーと除外のルール、検索インデックスとキャッシュの仕組みについては、Settings と環境変数の リファレンス とレイヤー システムに詳しく記載されています。

MCP エージェントアクセス

組み込みの MCP エンドポイントはデフォルトで無効になっており、http://127.0.0.1:42824/mcp で利用できます。独自のベアラートークンを使用し、読み取り専用アクセスでもトークンが必要です。これは /mcp がウェブの認証レイヤーを迂回するためです。Settings → Agent access (MCP) で有効にして、トークンを生成してください。書き込みアクセスは別途有効にし、エージェントが行う操作を信頼できる場合にのみ許可してください。変更は再起動なしで、以降の MCP リクエストにすぐ適用されます。

クライアントのセットアップ(Claude Code、Codex、OpenClaw、Hermes)、すべてのツール呼び出しで必要となる Vault スコープの仕様、添付ファイルのアップロード方法については、エージェントを 接続する と MCP ツールの リファレンスをご覧ください。

バージョン管理と Git 同期

バージョン管理はサーバーごとではなく、Vault ごとに設定します。その Vault の Settings ページで、Git なし、ローカル履歴、プルのみ、または双方向を選択してください。マージの競合は必ず人が解決できる状態で保持されます。Hatchdoor が未コミットの手動による Vault の編集を上書きして強制的にチェックアウトすることはありません。

セットアップについてはGit 管理の Vault をセットアップする 方法をご覧ください。レジストリ導入前の単一 Vault デプロイメントからアップグレードする場合は、 docs/migrations/legacy-single-vault.mdをご覧ください。

Docker を使用せずに実行する

just がインストールされている場合、just dev-start を実行すると、以下の手動手順に加えて PID の追跡や、サーバーの重複起動、古いビルドキャッシュディレクトリの蓄積を防止できます。just dev-stop は両方を正常に停止し、just --list ではその他のコマンド(dev-status、dev-clean、prod-check)を確認できます。各レシピの動作については justfile を参照してください。ビルド成果物は、リンクされたワークツリー間でプライマリチェックアウトを通じて共有されます。CARGO_TARGET_DIR、CARGO_HOME、HATCHDOOR_TMPDIR の値を明示的に指定すると、ポータブルなデフォルト値を上書きできます。

それ以外の場合は、まずフロントエンドを一度ビルドします。

cd frontend
npm ci
npm run build
cd ..

バックエンドを実行します。

cargo run

デフォルトでは、ローカルソースの実行は 127.0.0.1:42824 にバインドされ、Vault がない状態で起動します。Settings で追加するか、POST /api/v1/vaults を使用してください。開発用の Vault 一式をすぐに用意するには、代わりに just dev-start を使用してください(AGENTS.md を参照)。

フロントエンドの開発モードを使用する場合:

# terminal 1
cargo run

# terminal 2
cd frontend
npm run dev

初回起動時のモデル選択は、ローカル開発にも適用されます。Hatchdoor はデフォルトでモデルを ./models に保存するため、モデルを事前に取得するコマンドは必要ありません。

トラブルシューティング

Hatchdoor が 0.0.0.0 での起動を拒否する

HATCHDOOR_WEB_BEARER_TOKEN を設定するか、127.0.0.1 にバインドするか、読み取り専用の公開デモを実行するために HATCHDOOR_DEMO_MODE=true を有効にしてください。これは意図的な動作です。ループバック以外にバインドすると、Vault がネットワークに公開される可能性があります。

アプリを起動しても Vault がない、またはノートフォルダーが一覧に表示されない

新規インストールでは、Vault を追加するまで Vault はありません。セットアップチェックリストで Add your notes を選択するか、Settings → Add a Vault を選択してください。フォルダー一覧が空の場合や、フォルダーが一覧にない場合、ほとんどの場合、コンテナーに空のディレクトリがマウントされています。.env の HOST_VAULT_PATH に誤りがないこと、また、古い Docker ボリュームがマウントを隠していないことを確認してください。

書き込み権限の問題、MCP の 401/403、git の同期に関する問題などについては、ユーザードキュメントのよくある問題のトラブルシューティング方法を参照してください。すべての HTTP エンドポイントについては、HTTP API リファレンスに記載されています。

セキュリティに関する注意事項

  • 長く、ランダムな HATCHDOOR_WEB_BEARER_TOKEN を使用してください。
  • Hatchdoor の前段に HTTPS を設定せず、公開しないでください。
  • HATCHDOOR_DEMO_MODE=true は、閲覧のみ可能な公開テストインスタンスでのみ使用してください。
  • 必要でない限り、MCP を無効にしておいてください。
  • MCP の書き込みモードは強力な機能です。コンテンツの作成、編集、移動、削除、インポートが可能です。
  • SQLite キャッシュは Vault の外に置いてください。
  • .env を git に含めないでください。
  • コンテナーを起動する前に、Docker ボリュームのパスを確認してください。

開発

バックエンドのチェック:

cargo fmt --check
CARGO_BUILD_JOBS=1 cargo clippy --all-targets -- -D warnings
CARGO_BUILD_JOBS=1 cargo test

フロントエンドのチェック:

cd frontend
npm run format:check
npm run typecheck
npm run lint
npm test
npm run build

just release-prepare と just release-publish はリリースを作成し、Docker イメージを公開します。リリース手順書を参照してください。リリースにはメンテナーのビルドマシンと認証情報が必要なため、コントリビューターはリリースを作成できません。イメージをローカルでビルドする方法については、コンテナーのビルドターゲットと Cargo キャッシュを参照してください。

プロジェクトドキュメント

  • ユーザードキュメント:Hatchdoor のセットアップ、設定、日常的な使用方法を説明するガイドです。Hatchdoor 自体の保管庫でホストされています。ソースは docs/user-vault にあり、すべてのインストールには、そのバージョンと同じページがヘルプと /docs/ に含まれています。
  • ライブデモ:4 つのサンプル保管庫を備えた、一般公開の読み取り専用インスタンスです。
  • 変更履歴と リリース:各バージョンでの変更内容です。
  • ドキュメントインデックス:アーキテクチャ、コラボレーション、ロードマップ、調査、メンテナンス、過去の記録を掲載しています。
  • 製品ロードマップ:製品全体の方向性の草案と、そこから派生する作業項目です。
  • デザインシステム:フロントエンドで使用するビジュアルトークン、コンポーネントのパターン、レイアウトルール、インタラクションの状態です。
  • セマンティック検索戦略:ランタイムの処理経路でハイブリッド検索やクロスエンコーダーによる再ランキングではなく、純粋なセマンティック検索を提供する決定を記録しています。

ライセンス

Hatchdoor は GNU Affero General Public License v3.0 のみの下でライセンスされています。 LICENSE をご覧ください。

第三者の素材(バンドルされたアイコンと、実行時にダウンロードされる埋め込みモデル)は、 THIRD_PARTY_NOTICES に記録されています。

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。