メインコンテンツへ移動
AIチュートリアル

FastAPI、SQLite、MCPでローカルファイル知識ベースを構築・利用する

FastAPI知識ベースのインストール、SQLiteデータベースの初期化、ユーザー認証、ドキュメントのアップロードと整理、対応ファイルのプレビュー、付属の読み取り専用MCPサービスを介したAIエージェントとの接続方法を学びます。

約16分で読了
FastAPI、SQLite、MCPでローカルファイル知識ベースを構築・利用する

概要

ナレッジベース フェーズ1は、FastAPI、SQLite、ローカルファイルシステムストレージで構築された、実用最小限のファイルナレッジベースです。認証付きドキュメント管理、ネストされたフォルダー、ブラウザー内でのローカルプレビュー、メタデータとタグ、管理者向けツール、監査情報、Model Context Protocol（MCP）を介したAIエージェント向けの読み取り専用アクセスをサポートします。

このフェーズは意図的に軽量化されています。Docker、PostgreSQL、MinIO、LibreOffice、ONLYOFFICE、その他の稼働中のデータベースサービスは必要ありません。PostgreSQLとオブジェクトストレージへの移行は、後のフェーズで行います。

プロジェクトが提供する機能

  • 管理者によるユーザー作成、ログイン、JWT認証。
  • ネストされたフォルダーとパンくずナビゲーションを備えた公開ナレッジベース。
  • フォルダー単位のドキュメント一覧表示、単一ファイルのアップロード、バッチアップロード。
  • PDF、テキスト、Markdown、HTML、画像、PowerPoint、Word、Excelファイルのサポート。
  • ドキュメントのメタデータ、タグ、所有者、アップロードユーザーの情報。
  • 元ファイルのプレビューとダウンロード。
  • テキスト、Markdown、PDF、DOCX、XLSX、PPTX、画像のアプリ内閲覧。
  • 旧形式のDOC、XLS、PPTファイルに対するベストエフォートのテキスト抽出。
  • 所有者のみが行えるドキュメント編集、論理削除、復元、フォルダー名の変更、空フォルダーの削除。
  • 削除したドキュメント用のごみ箱。
  • スコープをまたいだドキュメントとフォルダーのコピー。再帰的なフォルダーコピーと物理ストレージの複製を含みます。
  • 管理者のみが利用できるユーザー管理、監査ログ、MCP呼び出しログ。
  • 読み取り専用REST API、自動生成されたOpenAPIドキュメント、MCP統合。

ストレージの仕組み

アプリケーションはbackend/data/配下に実行時ファイルを作成します。SQLiteデータベースはbackend/data/knowledge_base.dbとして保存され、アップロードされたファイルと生成されたMarkdownファイルはbackend/data/storage/配下に配置されます。

ローカルストレージにはパストラバーサル対策が含まれています。既存のDocker Compose設定は、後のPostgreSQLおよびオブジェクトストレージへの移行を目的としており、このフェーズでは必要ありません。

バックエンドをインストールする

1. 環境ファイルを作成する

PowerShellを開き、リポジトリのbackendディレクトリに移動して、ルート環境テンプレートをbackend/.envにコピーします。

cd backend
Copy-Item ..\.env.example .env

運用設定は.env.example、backend/app/core/config.py、およびscripts/配下のPowerShell制御ファイルで定義されています。

2. Python仮想環境を作成する

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

これらのコマンドはbackendディレクトリで実行します。仮想環境を有効にすると、プロジェクトのパッケージをグローバルなPythonインストール環境から分離できます。

3. SQLiteを初期化する

python -m app.db.init_db

このコマンドは、必要なSQLiteテーブルを初期化または再作成します。テーブルの再作成は既存データに影響する可能性があるため、ドキュメントの保存を開始した後は慎重に扱ってください。

4. FastAPIを起動する

uvicorn app.main:app --reload

開発サーバーはhttp://127.0.0.1:8000で利用できるようになります。--reloadオプションを指定すると、ソースファイルの変更時にアプリケーションが自動的に再読み込みされます。

5. APIドキュメントを開く

http://127.0.0.1:8000/docsにアクセスして、自動生成されたOpenAPIエンドポイントを確認・試行できます。

インストールを確認する

テストを実行するには、バックエンドディレクトリをPYTHONPATHに設定する必要があります。Windowsのコマンドプロンプトでは、次を実行します。

set PYTHONPATH=.
python -m pytest

PowerShellでは、次を使用します。

$env:PYTHONPATH = "."
python -m pytest

リポジトリには、サービスの起動、再起動、停止、状態確認を行うためのPowerShell制御ファイルもscripts/配下に用意されています。

REST APIで認証する

ユーザーは管理者が作成します。アカウントを取得したら、ユーザー名とパスワードをログインエンドポイントに送信してください。レスポンスには、認証済みリクエストに必要なトークンが含まれます。

$body = @{
  username = "demo"
  password = "password-123"
} | ConvertTo-Json

$response = Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/auth/login `
  -ContentType "application/json" `
  -Body $body

$response

返されたアクセストークンをコピーし、Bearer認証情報として使用します。トークンの権限は、認証されたユーザーの本人情報とロールに従います。

ドキュメントをアップロードする

アップロードエンドポイントはマルチパートフォームデータを受け付けます。ナレッジベースID、任意のタグ、ファイル、Bearerトークンを指定します。

$token = "<access_token>"
$knowledgeBaseId = 1

curl.exe `
  -X POST `
  "http://127.0.0.1:8000/api/v1/documents/upload" `
  -H "Authorization: Bearer $token" `
  -F "knowledge_base_id=$knowledgeBaseId" `
  -F "tags=制度,测试" `
  -F "file=@D:\path\to\guide.txt"

このプロジェクトは、個別アップロードとバッチアップロードの両方をサポートします。アップロードされた元ファイルはローカルストレージに保持され、対応するコンテンツはアプリ内リーダーで開くことができます。

フォルダーを作成して使用する

フォルダーエンドポイントにナレッジベースIDと名前をPOSTして、フォルダーを作成します。

$body = @{
  knowledge_base_id = 1
  name = "实验方案"
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/folders `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body $body

特定のフォルダーにアップロードするには、マルチパートアップロードフォームにfolder_idを追加します。Webインターフェースでは、フォルダーを選択すると自動的に追加されます。

ナレッジベースセレクターのデフォルトは全部で、「すべて」を意味します。このビューには、すべての公開ナレッジベースにあるルートドキュメントとフォルダーが表示されます。フォルダーを作成するときは、ダイアログで保存先のナレッジベースを選択してください。「すべてのナレッジベース」ビューからアップロードすると、フォルダーを選択していない限り、最初に利用可能なナレッジベースが使用されます。

ブラウザー上のローカルプレビューを理解する

フロントエンドは認証済みAPIを通じてファイルを取得し、ブラウザーのメモリ上に保持してローカルでレンダリングします。DOCX、PPTX、XLS、XLSXにはvue3-office-preview、PDFには@vue3-office/vue-pdf、Markdownには@deot/docs-markdownを使用します。PPTXのレンダリングには、同梱のpptx-rendererを使用します。

この方式では、LibreOffice、ONLYOFFICE、Docker、PythonのドキュメントプレビューSDKは必要ありません。元のファイルはローカルストレージに保存されたままです。Markdownの抽出と、従来形式の.doc、.xls、.pptファイルに対するフォールバック処理は、引き続きバックエンドの責任です。

MCPでAIエージェントを接続する

リポジトリには、読み取り専用の独立したMCPサービスが含まれています。このサービスは、FastAPIアプリケーションのSQLiteデータベース、ローカルストレージ、JWTシークレット、ドキュメントリーダーを共有します。Phase 1で利用できるツールは次のとおりです。

  • list_knowledge_bases
  • list_documents
  • search_knowledge
  • get_document
  • get_document_metadata

MCPプロセスでは、アップロード、移動、削除、フォルダー管理はできません。ドキュメントへのアクセスは、関連付けられたユーザーに読み取りが許可されている範囲に制限されます。

MCPの依存関係をインストールする

backendディレクトリから、MCP専用の仮想環境を作成します。

cd backend
python -m venv .mcp-venv
.\.mcp-venv\Scripts\python.exe -m pip install -r requirements-mcp.txt

標準入力と標準出力でMCPを実行する

APIと同じデータベースおよびストレージ設定でMCPプロセスを構成します。ログインアクセストークンをKB_MCP_TOKENに設定してから、サーバーを起動します。

$env:PYTHONPATH = "."
$env:KB_MCP_TOKEN = "<access_token>"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

ローカルのstdioクライアントでは、KB_MCP_TOKENを省略できます。その場合、エージェントはユーザー名とパスワードを指定してauthenticateツールを1回呼び出す必要があります。生成された短時間有効のセッションは、MCPプロセスのメモリ内にのみ存在します。

stdio MCPサービスに通常のprint()呼び出しを追加しないでください。標準出力はプロトコルメッセージに使用されるため、診断情報は標準エラーに書き込む必要があります。

MCPスモークテストを実行する

$env:PYTHONPATH = "."
.\.mcp-venv\Scripts\python.exe scripts\mcp_stdio_smoke.py

Streamable HTTPでMCPを公開する

同じMCPモジュールを起動する前に、トランスポート、リッスンアドレス、ポート、パス、ステートレスモードを設定します。

$env:PYTHONPATH = "."
$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "0.0.0.0"
$env:MCP_PORT = "8020"
$env:MCP_PATH = "/mcp"
$env:MCP_STATELESS_HTTP = "true"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

HTTPSリバースプロキシを設定すると、公開エンドポイントはhttps://your-domain/mcpにできます。リモートクライアントはAuthorization: Bearer <access_token>を送信し、API接続と同じ保護されたBearer認証情報を使用してください。

ブラウザーページ/mcp-token.htmlでは、パスワードを読み取ったり保存したりせずに、ログイン中のアカウント用のMCPトークンを要求できます。管理者は/admin.htmlを使用して、ユーザーの状態、ロール、パスワード、ユーザーごとのMCPトークン有効期限ポリシーを管理できます。永続的な長期間有効のトークンも設定できます。

高度な運用のヒント

  • APIとMCPの設定を一致させる。両サービスは同じSQLiteデータベースとストレージパスを参照し、同じJWTシークレットを使用する必要があります。
  • 最小権限のIDを使用する。MCPエージェントは、トークンのユーザーが読み取り可能なドキュメント範囲を引き継ぎます。
  • Bearerトークンを保護する。APIまたはMCPの認証情報をソース管理、ログ、通常のコンソール出力に記録しないでください。
  • stdioプロトコルを維持する。MCPの診断情報は標準出力ではなく標準エラーに送信します。
  • リモートではHTTPSを使用する。ローカルマシンの外部に公開する前に、Streamable HTTPエンドポイントをHTTPSリバースプロキシの背後に配置します。
  • Phase 1の範囲を把握する。Docker Compose、PostgreSQL、オブジェクトストレージは移行対象であり、現在の実行時要件ではありません。
  • 所有者制限を確認する。ドキュメントの編集、論理削除、復元、フォルダー名の変更、空フォルダーの削除は、所有者だけが実行できます。
  • 生成されたAPIドキュメントを使用する。/docsページは、ここに示した例以外で利用可能なリクエストフィールドとレスポンスを確認する最も直接的な方法です。

まとめ

Knowledge Base Phase 1は、認証済みのファイル整理、プレビュー、取得、エージェントアクセスのための実用的なローカル基盤を提供します。Python、SQLite、ローカルストレージだけでサービスを初期化し、構造化されたドキュメントコレクションをアップロードし、フォルダーとメタデータを管理し、ローカルstdioまたはリモートのStreamable HTTP MCPトランスポートを通じて読み取り専用のナレッジツールを安全に公開できます。