LLMScribe

LLMScribe

あらゆるコードリポジトリを、クリーンで構造化された決定論的なデータに変換します。 AI も、埋め込みも、隠れたランキングもありません。オープンソースで、無料のホスト型 MCP として利用できます。

ねえ、そこのあなた、スターを付けてください :)

LLMScribe を選ぶ理由

• 決定論的：同じ入力から、予測可能な出力が得られます。LLM、埋め込み、AI によるランキングはありません
• リポジトリ優先：ローカルプロジェクトと公開 GitHub リポジトリで動作し、クローンは不要です
• 構造化された出力：すべての操作で機械可読な JSON を出力します
• すばやい探索：プロジェクトをマップし、検索して、必要なものだけを取得できます
• 依存関係を把握：ローカル、外部、未解決の依存関係を理解できます
• Git を認識：ステータスと統合差分を確認できます
• エージェント対応：設定ブロックを 1 つ指定するだけで、LLMScribe をあらゆる AI エージェントや MCP クライアントに接続できます
• 複数のインターフェース：CLI、MCP、GUI、プログラムから利用できるコアが、すべて同じエンジンを共有します
• オープンソース：Apache-2.0 ライセンスで、セルフホスト可能、永久に無料です

LLMScribe は、自らがインテリジェンスになることを目指していません。インテリジェンスに必要なデータを提供します。

機能の概要

コアツール

その他

クイックスタート

PyPI から LLMScribe をインストールします。

pip install llmscribe

その後、任意のプロジェクトディレクトリを指定するか、（MCP ツールを介して）公開 GitHub リポジトリを指定します。API キーは必要ありません。

以下の project_map(...)、search(...)、read(...) のスニペットは、MCP ツールの呼び出しを示しています。同じ操作は CLI（ローカルディレクトリ）からも、llmscribe.core 経由の Python からも利用できます（Python API を参照）。

マップ

ファイルの内容を含まない、すっきりとしたディレクトリツリーを生成します。見慣れないリポジトリを調べる際の最初のステップとして最適です。

project_map()

# or a public GitHub repo, no clone needed
project_map(repo="owner/repo")

llmscribe map
llmscribe map --json

project_map

出力：

src/
├── api/
│   ├── routes.py
│   └── auth.py
├── models/
│   └── user.py
└── main.py

検索

ファイルパス、ファイル名、ファイルの内容、個々の行を横断して検索します。検索結果は意図的に決定論的です。LLMScribe は、意図を推測しようとはしません。

search(query="authentication")

# or a public GitHub repo
search(query="authentication", repo="owner/repo")

llmscribe search "authentication"
llmscribe search "authentication" --json

search

各一致には、ファイルパス、行番号、一致した行、一致したテキスト、一致タイプ（filename または content）が含まれます。結果はパス、次に行番号の順で並び、最大 1,000 件に制限されます。バイナリファイルとサイズが大きすぎるファイルはスキップされます。

出力（--json、data.matches）：

[
  {
    "file_path": "src/auth/service.py",
    "line_number": 12,
    "line_content": "def authenticate(user, password):",
    "match_type": "content",
    "matched_text": "authenticate"
  }
]

読み取り

特定のファイルの内容を安全に取得します。LLMScribe はパスを検証し、プロジェクト外へのパストラバーサルを防ぎます。

read(file_path="src/auth/service.py")

# or a public GitHub repo
read(file_path="src/main.py", repo="owner/repo")

llmscribe read src/auth/service.py

read

path と repo は同時に指定できません。ローカルプロジェクトには path を、公開 GitHub リポジトリには repo を使用してください。

エージェントを強化する

リポジトリ全体をコンテキストウィンドウに入れる代わりに、エージェントは必要なものだけを段階的に取得できます。

1. project_map()
      ↓
2. search("authentication")
      ↓
3. read("src/auth/service.py")
      ↓
4. project_dependencies("src/auth/service.py")
      ↓
5. read_many([...])

MCP

MCP 対応クライアント（Cursor、Claude、Windsurf など）をリポジトリに接続します。

無料のホスト型 MCP。 インストールは不要です。

{
  "mcpServers": {
    "llmscribe": {
      "url": "https://llmscribe.onrender.com/mcp"
    }
  }
}

カスタムのリモートコネクターに対応するクライアントでは、エンドポイントを指定するだけです：https://llmscribe.onrender.com/mcp

公開エンドポイントは試用に便利です。プライベートコードや本番環境のワークロードには、代わりに LLMScribe をセルフホストしてください。

ローカル MCP。 stdio 経由でマシン上で実行します。

{
  "mcpServers": {
    "llmscribe": {
      "command": "llmscribe-mcp"
    }
  }
}

{
  "mcpServers": {
    "llmscribe": {
      "command": "python",
      "args": ["-m", "llmscribe.mcp"]
    }
  }
}

利用可能なツール

project_map
project_overview
search
read
read_many
project_dependencies
project_diff

その他のツール

複数ファイルの読み取り

1 回の操作で複数のファイルを取得します。一部の取得に失敗しても処理を継続できるため、問題のあるファイルが 1 つあってもリクエスト全体が無効になりません。

read_many([
    "src/auth/service.py",
    "src/auth/models.py",
    "src/api/login.py"
])

llmscribe read-many src/auth/service.py src/api/login.py

依存関係

ファイルを取り巻く依存関係を調べます。LLMScribe は、ローカル依存関係、外部依存関係、解決できない依存関係、およびこのファイルに依存するファイルを特定します。

project_dependencies("src/auth/service.py")

llmscribe dependencies src/auth/service.py --json

出力：

src/auth/service.py
│
├── depends on
│   ├── auth/models.py
│   ├── auth/config.py
│   └── auth/utils.py
│
└── used by
    ├── api/login.py
    └── tests/test_auth.py

ファイルの変更がもたらす潜在的な影響を判断する際に、特に役立ちます。

差分

Git を使用してリポジトリの変更を調べます。Git のステータス、未ステージの変更、ステージ済みの変更、特定のコミット、統合差分に対応しています。

llmscribe diff

これにより、アプリケーションやエージェントは現在のリポジトリだけでなく、何が変更されたかも把握できます。

概要

ディレクトリ構造、対応するテキストファイルの内容、構造化されたプロジェクト情報を含む、プロジェクト全体のスナップショットを生成します。

llmscribe overview

小規模から中規模のプロジェクトに最適です。大規模なリポジトリでは、代わりに推奨ワークフローを使用してください。

map → search → read

CLI

すべてのコマンドは --json を指定して機械可読な JSON を返すことができます。そのため、CLI はスクリプト、自動化、開発者ツールの構成要素として利用できます。

llmscribe map
llmscribe overview
llmscribe search "authentication"
llmscribe read src/auth/service.py
llmscribe read-many src/auth/service.py src/api/login.py
llmscribe dependencies src/auth/service.py
llmscribe diff

# machine-readable output
llmscribe map --json
llmscribe search "auth" --json
llmscribe dependencies src/auth/service.py --json

セルフホスティング

プライベートリポジトリ、チーム、社内開発者ツール、本番アプリケーション向けに、独自の HTTP MCP サーバーを実行します。

ローカルで実行

pip install llmscribe

MCP_TRANSPORT=http MCP_ALLOW_LOCAL_PATHS=1 llmscribe-mcp

サーバーは http://localhost:8000/mcp で利用できます。また、監視用に GET /health と GET /info が用意されています。

HTTP 経由では、ホスト型サーバーが自身のディスクを公開しないよう、path 引数はデフォルトで無効になっています。任意のローカルパスを許可するには MCP_ALLOW_LOCAL_PATHS=1 を設定してください（信頼できるマシンでのみ使用してください）。特定のディレクトリを許可するには MCP_ALLOWED_ROOTS=/srv/a:/srv/b を設定してください。GitHub リポジトリ（repo=）は常に使用できます。

Docker

docker build -t llmscribe-mcp .

docker run -p 8000:8000 -e MCP_ALLOWED_HOSTS="localhost,localhost:*,mcp.example.com" llmscribe-mcp

このイメージは、非特権ユーザーとして MCP_TRANSPORT=http を設定した状態で python -m llmscribe.mcp を実行し、healthcheck 付きの /health を備えています。

Railway

railway up

環境変数

プロセスは 1 つだけ実行してください（キャッシュと MCP セッションはメモリ上に保持されます）。後方互換性のため、MCP_TRANSPORT を指定せずに PORT を設定すると HTTP が選択されますが、MCP_TRANSPORT=http を明示的に設定してください。

Python API

from pathlib import Path
from llmscribe.core import project_map, search_project, read_file, read_files, analyze_dependencies, get_git_diff, LLMScribeError

root = Path(".")
print(project_map(root).tree)
print(search_project("auth", root).to_dict())
print(read_files(["README.md", "missing.py"], root).to_dict())   # per-file errors, never raises
try:
    analyze_dependencies("src/app.py", root)
except LLMScribeError as err:      # err.code is a stable machine-readable code
    print(err.code, err.message)

動作のリファレンス

無視ルール。 デフォルト値（.git、node_modules、venv、dist、build、.env、*.log、…）、ルートの .gitignore、およびネストされた .gitignore ファイルは、実際の Git のセマンティクス（ワイルドカード、ディレクトリ、! による否定、ルート基準のパターン）に従って適用されます。無視対象でない限り、隠しファイルも含まれます。シンボリックリンクはたどられず、一覧にも表示されません。

サポート対象のテキストファイル。 既知のソース／設定／ドキュメント用拡張子に加え、Dockerfile、Makefile、LICENSE、.gitignore などのファイル名が対象です。それ以外のファイルはツリーに表示されますが、読み取りや検索はできません。

制限（一元管理元：llmscribe.core.limits）：概要／read_many あたりのコンテンツ文字数は 400,000、read_many あたりのファイル数は 50、検索結果は 1,000 件、マップエントリ数は 20,000、ファイルサイズは 2 MiB、差分の文字数は 200,000、アーカイブのダウンロードサイズは 100 MiB、アーカイブあたり 250 MiB／100,000 エントリです。切り詰められた内容は報告されます（truncated、truncation_note、omitted_files）。

エラー。 すべての失敗には固定のコードがあります：invalid_argument、invalid_path、file_not_found、unsupported_file_type、binary_file、file_too_large、read_error、repository_not_found、not_a_repository、repository_too_large、github_rate_limited、github_auth_required、github_unavailable、git_unavailable、unsupported_operation、internal_error。JSON：{"ok": false, "tool": "...", "error": {"code": "...", "message": "..."}}。

依存関係。 Python、JavaScript/TypeScript、Java、Go、Rust、C/C++ に対応しています。各参照は local、stdlib、external（リポジトリ内になく、サードパーティ製と見なされるもの）、または unresolved（一致するものがない相対／ローカル参照）です。used_by には逆依存関係が列挙されます。ローカルソースと GitHub ソースで同じように動作します。

GitHub。 パブリックリポジトリ（および GITHUB_TOKEN を使うプライベートリポジトリ）は、1 つの zip アーカイブとして取得され、所有者／リポジトリ／ref／認証情報ごとにメモリへキャッシュされます。クローンもディスクへの書き込みも行いません。GitHub 上の project_diff は compare API を使用し、commit（ベース）が必須で、ref（ヘッド）は任意です。staged はローカルでのみ使用できます。

Git diff（ローカル）。 git は引数リストとともに実行され、タイムアウトは 30 秒、環境変数は最小限に設定され、外部 diff／textconv ドライバーは使用されません。

移行に関する注意事項

• 旧ツール名（project_get_file、project_get_files、project_search、project_list_files）は廃止されました。read、read_many、searchを使用してください。
• エラーコードpath_traversalはinvalid_pathに、not_text_fileはunsupported_file_typeに変更されました。
• project_dependenciesの結果では、all_local_files／all_external_deps／all_unresolvedがused_byとカテゴリ別リストに置き換えられました（stdlib_dependenciesが追加されています）。
• llmscribe.coreの関数は、ルートが不正な場合にFileNotFoundErrorではなくLLMScribeErrorを発生させます。依存関係プロバイダークラスとllmscribe.github.providerヘルパーは削除されました。
• HTTP経由でローカルのpathにアクセスするには、MCP_ALLOW_LOCAL_PATHSまたはMCP_ALLOWED_ROOTSが必要になりました。

アーキテクチャ

すべてのインターフェースが共通のコアエンジンを使用するため、どこでも一貫した動作が保たれます。

                         Repository
                             │
               ┌─────────────┴─────────────┐
               │                           │
          Local Project               GitHub Repo
               │                           │
               └─────────────┬─────────────┘
                             ▼
                     LLMScribe Core
                             │
       ┌─────────────────────┼─────────────────────┐
       │                     │                     │
       ▼                     ▼                     ▼
      CLI                   MCP                   GUI
       │                     │
       └──────────────┬──────┘
                      ▼
              Structured Output
                   / JSON

基本方針

LLMScribeは意図的にシンプルさを保っています。目標はリポジトリを「より賢く」することではありません。リポジトリをソフトウェアから利用可能にすることです。

提供するもの

• リポジトリの抽出
• 決定論的な検索
• 構造化されたプロジェクトデータ
• ファイルの取得
• 依存関係情報
• Git情報
• 複数のインターフェース

提供しないもの

• ❌ AIが生成する回答
• ❌ 埋め込みベースの検索
• ❌ セマンティックランキング
• ❌ 自律的なコーディング
• ❌ AIコーディングエージェント
• ❌ 汎用Gitクライアント

ユースケース

• AIコーディングエージェント
• MCPアプリケーション
• 開発者向けツール
• コード検索インターフェース
• リポジトリエクスプローラー
• ドキュメントシステム
• コード解析パイプライン
• 自動化スクリプト
• ローカルLLMアプリケーション
• 見慣れないオープンソースプロジェクトの探索

オープンソース版とホステッド版

LLMScribeはApache License 2.0のもとでオープンソースとして公開されています。ローカルで実行し、ソースを確認し、変更し、セルフホストし、独自の連携機能を構築できます。

ホステッドMCPエンドポイントは、インストール不要で手軽に試せる選択肢を提供します。一方、オープンソースプロジェクトではすべてを自由に管理できます。

リソース

• ウェブサイト： https://llmscribe.vercel.app
• GitHub： https://github.com/AMRITO-KUNDU/llmscribe
• PyPI： https://pypi.org/project/llmscribe/
• パブリックMCP： https://llmscribe.onrender.com/mcp
• 課題： https://github.com/AMRITO-KUNDU/llmscribe/issues
• コントリビューション： https://github.com/AMRITO-KUNDU/llmscribe/blob/main/CONTRIBUTING.md

コントリビューション

コントリビューションを歓迎します。リポジトリの抽出、検索、依存関係の解析、インターフェース、連携機能、ドキュメントの改善に取り組みたい場合は、プルリクエストを作成する前にコントリビューションガイドをご確認ください。

ライセンス

LLMScribeはApache License 2.0のもとでライセンスされています。詳しくはLICENSEファイルをご覧ください。