Algenta MCP Server

カスタム Mojo カーネルが Algenta の速度を支えています。チームが Mojo を書く必要はありません。ブロックは Python と TypeScript で操作できます。私たちのインフラではなく、お客様のインフラ上で動作します。これらの SDK を使って、Python と TypeScript からエンジンを呼び出せます。ガバナンスされたデータクエリ、モンテカルロシミュレーションとレコメンデーション、各実行で適用されたポリシーとスキーマのスナップショットを固定する実行レシート付きの意思決定メモリー、ヒューマン・イン・ザ・ループ承認を伴うエージェント実行、管理対象コネクター、そして完全な監査証跡に、型安全にアクセスできます。これらはクライアント側の慣習ではなく、エンジンによって強制されます。

MCP サーバー

MCP サーバー（algenta-mcp） — Algenta の公式 MCP サーバーは、このリポジトリの packages/mcp/ にあります（実装： packages/mcp/algenta_mcp。デフォルトでは stdio トランスポートを使用し、Streamable HTTP もオプションで利用できます）。pip install algenta-mcp でインストールし、algenta-mcp コマンドとして実行できます。また、公式 MCP Registry に io.github.thyn-ai/algenta として登録されています。フレームワークインテグレーション（LangChain、LlamaIndex、Vercel AI SDK など）は、別のリポジトリである thyn-ai/algenta-integrations にあります。MCP サーバーは含まれていません。

イントロスペクション（initialize／tools/list）には認証情報は必要ありません。ツールの実行には、無料のコミュニティログインが必要です。algenta.ai でデバイスを登録してください（無料）。algenta login を実行するか、 https://app.algenta.ai/dashboard/api-keys でキーを作成し、ALGENTA_API_KEY を設定してください。

インストール

pip install algenta-sdk       # Python 3.12+
npm install algenta-sdk       # TypeScript / JavaScript, Node.js 18+

クイックスタート

どちらのクライアントも環境変数 ALGENTA_API_KEY を読み取り、デフォルトでは Algenta のホスト型 API https://api.algenta.ai を使用します。

Python — インポート名は decision_engine です（ 旧名称を参照）：

from decision_engine import AlgentaClient

client = AlgentaClient()  # reads ALGENTA_API_KEY; defaults to https://api.algenta.ai

datasets = client.list_datasets(search="orders", compact=True)
summary = client.get_dataset_summary(datasets.datasets[0].dataset_id)
result = client.query_with_metadata(
    {
        "dataset_id": summary.dataset_id,
        "metric": {"hint": "gross_revenue"},
        "aggregation": "sum",
    }
)
print(result.data.result)

TypeScript:

import { AlgentaClient } from "algenta-sdk";

const client = new AlgentaClient(); // reads ALGENTA_API_KEY; defaults to https://api.algenta.ai

const datasets = await client.listDatasets({ search: "orders", compact: true });
const summary = await client.getDatasetSummary(datasets.datasets[0].dataset_id);
const result = await client.queryWithMetadata({
  dataset_id: summary.dataset_id,
  metric: { hint: "gross_revenue" },
  aggregation: "sum",
});
console.log(result.data.result);

セルフホスト型エンジンを使用する場合 — クライアントを独自のデプロイ先に向けます。 Python では AlgentaClient(base_url="http://localhost:8000")、 TypeScript では new AlgentaClient({ baseUrl: "http://localhost:8000" }) を指定し、 運用担当者から提供された API キーを使用します。self_hosted と air_gapped のデプロイプロファイルはフェイルクローズで動作し、Algenta のクラウドに 暗黙的にフォールバックすることはありません。 thyn-ai/algenta-integrations のフレームワーク統合は、意図的に逆のデフォルトを採用しています。セルフホストを優先し、 ALGENTA_BASE_URL または明示的な base_url からエンドポイントを解決します。また、 ホスト型 API をデフォルトにしたり、そこにフォールバックしたりすることはありません。

ガバナンス付きクエリ、コネクター、シミュレーション、ジョブ、 トリガー、エージェントの実行、意思決定、リポジトリインテリジェンス、および TypeScript のローカル Runtime ファサードを含む API の全容は、 packages/python-sdk/README.md と packages/ts-sdk/README.md に記載されています。実行可能な プロジェクトは examples/ にあります。MCP サーバーはこのリポジトリ内にあります （上記のMCP サーバーを参照）。フレームワーク統合（LangChain、 LlamaIndex、Vercel AI SDK など）は、コンパニオンリポジトリ thyn-ai/algenta-integrations にあります。

エラー、再試行、タイムアウト

どちらの SDK も、同じ例外分類を使用します。すべてのエラーには HTTP ステータス、エンジンの機械可読な error_code が含まれます。また、Python では エンジンによって割り当てられた request_id も含まれます。検証エラーではさらに、 field_errors（Python）／fieldErrors（TypeScript）を使ってフィールドごとの詳細を確認できます。

例外	HTTP ステータス	発生条件	デフォルトで再試行
AuthenticationError	401	API キーがない、または無効	いいえ
NotFoundError	404	リソースが存在しない	いいえ
ValidationError	422	リクエストがスキーマ検証に失敗	いいえ
RateLimitError	429	クォータまたはレート制限を超過	はい — エンジンの Retry-After を尊重します（retry_after／retryAfter、デフォルトは 60s）
ServerError	5xx	エンジン側の障害	はい — 指数バックオフ
DecisionEngineError	任意	上記すべての基底クラス	—

一時的なネットワークエラーは、5xx レスポンスと同じポリシーで再試行されます。Python SDK はさらに、 レート制限コード inline_preview_rate_limited の場合には再試行しません。

設定	Python	TypeScript	デフォルト
リクエストのタイムアウト	timeout（秒）	timeout（ミリ秒）	120
リクエストごとの再試行回数	max_retries	maxRetries	3

旧名称

SDK は開発の途中で Algenta に改称されました。後方互換性のため、以下の旧名称も引き続き使用できます。既存のコードや デプロイ設定を変更する必要はありません。

• Python のインポート名 — PyPI パッケージは algenta-sdk ですが、 インポート可能なモジュール名は引き続き decision_engine です： from decision_engine import AlgentaClient。
• クライアントのエイリアス — CodnaClient（および Python の AsyncCodnaClient）は、 どちらの SDK でも引き続き AlgentaClient のエイリアスとしてエクスポートされます。
• 環境変数 — DE_API_KEY、DE_BASE_URL、および ALGENTA_API_URL は、正規の ALGENTA_API_KEY と ALGENTA_BASE_URL とともに 引き続き受け付けられます。

公開 API 契約では、旧名称が削除される前に 90 日間の非推奨期間 （DEPRECATION_WINDOW_DAYS）を設けることを保証しています。

Mojo を活用

エンジンの計算カーネル（シミュレーション、スコアリング、ローカルクエリの実行）は Mojo で記述されており、プロプライエタリです。署名済みの algenta-runtime-native ホイールとして 配布され、このリポジトリには含まれていません。

ここで、また Apache-2.0 ライセンスのもとでオープンになっているのは、両方の SDK、そこから生成される公開 API 契約、 クライアントとランタイムが使用するワイヤープロトコル、そして実行可能なサンプルです。これには、ネイティブランタイムを SDK 経由で呼び出す最小限のエンドツーエンドの手順を示す examples/mojo-quickstart/ も含まれます。

何がオープンソースですか？

このリポジトリには、Apache-2.0 ライセンスの Algenta の Python および TypeScript クライアント SDK と公式 MCP サーバー（packages/mcp/）が含まれています （LICENSE と NOTICE を参照）。

Algenta エンジン自体はクローズドソースであり、このリポジトリには含まれていません。 エンジンのライセンス、デバイスの利用資格、ワーカーの上限、 同時実行数の上限、Server Compute Units は、別途定める Algenta Engine ライセンスに従い、エンジンによって独立して適用されます。

SDK は単純な HTTP クライアントです。ライセンス署名キーも、利用資格を適用するロジックも、エンジンと共有する秘密情報も保持していません。すべての 利用資格の申告は、SDK ではなく、クローズドなエンジンによって独立して検証・適用されます。フォークしたり、すべてのチェックを削除したり、SDK を完全に独自の HTTP クライアントに置き換えたりしても、この SDK を変更または置き換えても、Algenta エンジンにライセンスされた実行容量は変わりません。 脆弱性報告に関する詳細は SECURITY.md を参照してください。

Algenta は、実行にホスト型推論やテレメトリを必要としません。有料ライセンスでは SDK の呼び出しごとに課金するのではなく、ローカル実行とガバナンスの容量が拡張されます。

リリースを検証する

release.yml によってビルドされるすべてのリリースは、次の項目に紐づいています。

• このリポジトリ内の保護された sdk-vX.Y.Z ソースタグ。
• そのタグが指す正確なコミット。
• エンジンのテストスイートでコミットが検証された後、内部リリースパイプラインによって署名されるリリース承認レコード。このレコードは、コミットとコントラクトファイルのダイジェストをリリースバージョンに紐づけます（releases/ を参照）。

release.yml は、上記すべてが個別に一致しない限り、ビルドも公開も行いません。詳細は scripts/verify_release_authorization.py を参照してください。

署名が導入された 2026 年 9 月以降に作成された各 GitHub Release には、ホイールとともに、sdist と release-manifest.json に加えて、次のものが含まれています。

• アセットごとの鍵不要の Sigstore 署名バンドル （<asset>.sigstore.json）。release.yml の実行自体によって署名されます。
• 3 つすべてのアセットを対象とする SLSA ビルド来歴（multiple.intoto.jsonl）。 SLSA generic generator から生成されます。

VERSION にリリースバージョンを設定し、アセットを両方に照らして確認するには （タグ sdk-v1.0.15 の場合、VERSION=1.0.15 とします）。

pipx run sigstore verify identity "algenta_sdk-${VERSION}-py3-none-any.whl" \
  --bundle "algenta_sdk-${VERSION}-py3-none-any.whl.sigstore.json" \
  --cert-oidc-issuer https://token.actions.githubusercontent.com \
  --cert-identity "https://github.com/thyn-ai/algenta-sdk/.github/workflows/release.yml@refs/tags/sdk-v${VERSION}"

slsa-verifier verify-artifact "algenta_sdk-${VERSION}-py3-none-any.whl" \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/thyn-ai/algenta-sdk \
  --source-tag "sdk-v${VERSION}"

workflow_dispatch 経由で release.yml が公開したリリースは、ディスパッチされたブランチから署名されているため、証明書の ID はタグではなく @refs/heads/main で終わります。どちらであるかはバンドルに記録されています。

バージョニング

両パッケージは 1 つの API 契約をラップしているため、同じバージョン番号を共有し、 セマンティックバージョニング に従います。

• パッチ — バグ修正とドキュメントの変更。API サーフェスに変更はありません。
• マイナー — 後方互換性のある追加（新しいメソッド、新しい任意フィールド）。
• メジャー — エクスポートされたシンボル、必須フィールド、または動作に対する破壊的変更。上記の非推奨化期間を通じて事前に告知されます。

リリース履歴は CHANGELOG.md にあります。

コントリビューション

バグ修正、フレームワークとの連携、ドキュメント、テストを歓迎します。CONTRIBUTING.mdをご覧ください。CLAはありません。GitHubの利用規約に従い、コントリビューションはApache-2.0のもとで受け入れ側と提供側の双方にライセンスされます。新しいAPI機能のリクエストには、通常、まずAlgentaの非公開APIへの変更が必要です。生成されたコントラクトファイルに対するPRではなく、機能を説明するイシューを作成してください（この点についてもCONTRIBUTING.mdで説明しています）。

CODE_OF_CONDUCT.mdもお読みください。

• セキュリティに関する報告 → SECURITY.md（公開イシューにはしないでください）
• プロジェクトの方針とメンテナンス → GOVERNANCE.md
• サポートを受ける → SUPPORT.md

コントリビューター

このプロジェクトに貢献してくださる皆さんに感謝します。all-contributors仕様に従い、コードに限らずあらゆる種類の貢献を認識し、感謝しています。

コミュニティ

• Discord
• ドキュメント
• [email protected]

関連リポジトリ

Algentaチームによる、Algenta関連のオープンソースツールです。Algentaエンジン自体はプロプライエタリですが、以下に挙げるものはすべてApache-2.0です。コードを管理するリポジトリであれば、どこでもイシューやディスカッションを歓迎します。

• thyn-ai/algenta-sdk（このリポジトリ） — Algenta向けのPythonおよびTypeScript SDKと公式MCPサーバー（packages/mcp/）：ガバナンスに基づくデータクエリ、シミュレーション、実行記録付きの意思決定メモリー、承認を伴うエージェント実行。
• thyn-ai/algenta-integrations — Algenta向けのフレームワーク連携：LangChain、LlamaIndex、pydantic-ai、MAF、Haystack、LiteLLM、Ray Serve、vLLM、Vercel AI SDK、n8n。
• thyn-ai/mojo-kernels — 人気のPython／TypeScriptライブラリ向けに、ドロップイン型アクセラレーターとして使えるクリーンルーム実装のMojoカーネル。ビット単位で完全に一致する動作と、純粋な言語によるフォールバックを備えています。
• thyn-ai/security-toolchain — チェックサム検証済みの固定セキュリティツールチェーン（Gitleaks、Opengrep、OSV-Scanner、Trivyの設定、actionlint）。すべてのthyn-aiリポジトリで、ローカルおよびCIで実行されます。
• thyn-ai/feedback — Algenta関連のオープンソースツールおよびCodna GitHub App向けの公開イシュー受付窓口です。
• thyn-ai/codna-action — Codna向けのGitHub Action。CLIと同じパッケージ化されたローカルランタイムを使って、CIでリポジトリを修正、レビュー、または保護します。