Octonet Mcp

@mostajs/net — Octonet

1つのスキーマ、11種類のトランスポート、13種類のデータベース、マルチテナント認証を標準搭載。 @mostajs エコシステム向けの、スキーマ駆動型マルチプロトコル API サーバーです。Fastify 上に TypeScript で構築され、さまざまな言語からの利用を想定して設計されています（ネイティブ NetClient 14 種類）。

作者：Dr Hamid MADANI <[email protected]> ホームページ：octonet.amia.fr · mcp.amia.fr

---

ソケットボード。 @mostajs/orm は 13 種類のデータベースに接続し、Octonet （@mostajs/net）は同じエンティティを 11 種類のトランスポート（REST、 WebSocket、gRPC、MQTT、AMQP など）で再公開します。さらに NetClient が 18 言語の クライアントに展開するため、どのランタイムからでも外部アプリをデータに接続できます。

---

目次

1. Octonet とは
2. 2 クリックで試す（T1 サンドボックス）
3. 3 段階のオンボーディングモデル
4. 11 種類のトランスポート
5. 13 種類のデータベース
6. マルチテナント認証
7. 汎用スコープレジストリ
8. マルチプロジェクト対応
9. クイックスタート（セルフホスト）
10. 設定（.env）
11. API エンドポイントリファレンス
12. アーキテクチャ
13. 起動シーケンス
14. 14 種類の多言語対応 NetClient
15. 本番環境へのデプロイ（amia.fr）
16. ライセンス

---

Octonet とは

Octonet（@mostajs/net）は、単一の @mostajs/orm スキーマを 11 種類のネットワークプロトコルとして同時に公開する、Node.js のマルチトランスポートサーバーです：REST、GraphQL、WebSocket、SSE、JSON-RPC、MCP、gRPC、tRPC、OData、NATS、Arrow Flight。

同じ User エンティティには、次のようにアクセスできます：

curl https://octonet.amia.fr/api/v1/User              # REST
curl https://octonet.amia.fr/graphql -d '{"query":...}'  # GraphQL
wscat -c wss://octonet.amia.fr/ws                     # WebSocket
curl -N https://octonet.amia.fr/mcp                   # MCP (Claude Desktop)
# … 7 more

@mostajs/orm（13 種類の SGBD 方言）を基盤としています。マルチテナントの ID 管理には @mostajs/rbac、@mostajs/auth、@mostajs/api-keys を使用します。マルチプロジェクトのルーティングには @mostajs/mproject を使用します。

Octonet は @mostajs 三部作の 第 2 の中枢です：

• #1 — @mostajs/orm：データ永続化（13 種類のデータベース）
• #2 — Octonet：マルチプロトコルトランスポート（11 種類のワイヤープロトコル）
• #3 — 多言語対応 NetClients：ネイティブクライアントライブラリ 14 種類（Java、.NET、Python、Go、Swift、Kotlin、Dart、Rust、PHP、Ruby、Elixir、Lua、Delphi、Unity）

---

2 クリックで試す（T1 サンドボックス）

14 種類のランタイムのいずれからでも、Octonet を最速で試す方法：

1. https://octonet.amia.fr/try を開きます
2. エイリアスを選択します（例：alice-42）
3. サンドボックス専用のスコープが設定された apikey を取得します

curl -X POST https://octonet.amia.fr/try \
  -H "Content-Type: application/json" \
  -d '{"alias":"alice-42"}'

# Response:
{
  "status": "ok",
  "data": {
    "alias": "alice-42",
    "projectSlug": "sandbox-alice-42",
    "apiKey": "sk_test_…(64 chars, shown ONCE)",
    "permissions": { "projects":["sandbox-alice-42"], "operations":["read","write"], "transports":["rest","mcp"] },
    "expiresAt": "2026-05-02T18:38:19.920Z",
    "quota": { "reqPerDay": 500 },
    "exampleCurl": "curl https://octonet.amia.fr/api/v1/sandbox-alice-42/User -H \"X-API-Key: sk_test_…\"",
    "mcpUrl": "https://octonet.amia.fr/mcp"
  }
}

サンドボックスの内容：

• 他のエイリアスから分離されたプライベートな SQLite ファイル
• User、Product、Order エンティティが事前に登録されています
• REST と MCP 経由で読み書き可能な CRUD
• 1 日あたり 500 リクエストの上限
• TTL は 7 日（アイドル状態の場合は自動削除）
• 無料、メールアドレス不要、不正利用防止のレート制限あり（IP あたり 1 時間に 10 個のサンドボックス）

apikey は 14 種類の NetClient のいずれでも使用できます：

# Java / .NET / Python / Go / etc.
export MOSTAJS_NET_URL=https://octonet.amia.fr
export MOSTAJS_NET_API_KEY=sk_test_…

---

3 層オンボーディングモデル

層	対象	認証	クォータ	ユースケース
T1 — パブリックサンドボックス /try	「10 分で試してみたい」	エイリアスのみ（メールアドレス不要）	500 リクエスト/日、TTL 7 日	NetClients のデモ、統合テスト
T2 — 登録済みアカウント octocloud.amia.fr	「実際に使いたい。無料で」	メールアドレス＋パスワード	10,000 リクエスト/日	個人用アプリ、サイドプロジェクト
T3 — セルフホスト npx @mostajs/net init	「データを自分の手元に置きたい」	ローカル管理者	なし	エンタープライズ、オンプレミス、AGPL

---

11 種類のトランスポート

登録済みスキーマから自動生成されます。環境変数で個別に切り替えられます（デフォルトではすべて有効）。

#	トランスポート	エンドポイント	ユースケース	備考
1	REST	/api/v1/{Entity} · /api/v1/{project}/{Entity}	汎用	エンティティごとに 15 個のルート（CRUD + count + search + aggregate + bulk + relations）
2	GraphQL	/graphql (POST)	高機能なフロントエンド	mercurius 経由でスキーマと GraphiQL IDE を自動生成
3	WebSocket	wss://…/ws	リアルタイム	イベント entity.created/updated/deleted/upserted をブロードキャスト
4	SSE	/events (GET stream)	モバイル／ブラウザー対応	サーバー送信イベント
5	JSON-RPC	/rpc (POST)	EVM 隣接、従来型	JSON-RPC 2.0 + メソッド検出
6	MCP	/mcp (POST/GET SSE)	AI エージェント（Claude、ChatGPT）	エンティティごとに 15 個のツールを自動生成（mcp.so に掲載）
7	gRPC	:50051	低レイテンシのサービス間通信	.proto を自動生成、エンティティごとに 6 個の RPC
8	tRPC	/trpc/{Entity}.{op}	TypeScript フルスタック	クライアント側の型生成
9	OData	/odata/{Collection} (+ $metadata)	SAP／Microsoft Dynamics	OData v4 ($filter、$select、$orderby)
10	NATS	mostajs.{Entity}.{op}	エッジでの Pub/Sub	リクエスト・リプライメッセージング
11	Arrow Flight	/arrow/*	列指向分析	ゼロコピーのストリーミング

同じスキーマで 11 種類の入口を利用でき、コード生成は不要です。

---

13 種類のデータベース

@mostajs/orm が提供する永続化ダイアレクト：

カテゴリー	データベース	ダイアレクト ID
主流の SQL	PostgreSQL、MySQL、MariaDB、SQLite	postgres、mysql、mariadb、sqlite
エンタープライズ向け SQL	Oracle、SQL Server、DB2、SAP HANA、HSQLDB、Sybase	oracle、mssql、db2、hana、hsqldb、sybase
NewSQL／クラウド	CockroachDB、Google Cloud Spanner	cockroachdb、spanner
NoSQL	MongoDB	mongodb

ダイアレクトの切り替えは、環境変数の 1 行を変更するだけです：

DB_DIALECT=postgres → DB_DIALECT=mongodb
SGBD_URI=postgresql://… → SGBD_URI=mongodb://…

---

マルチテナント認証

Octonet は、**スコープ付き API キー（マシン間通信向け）**に基づく認証ミドルウェアと、人間による管理向けの RBAC を使用します。アグノスティックなオーケストレーターは @mostajs/auth/lib/check-request.ts にあります。

リクエストの認証フロー

HTTP Request
  │
  ▼
authGuard (Fastify adapter)
  │
  ▼
checkRequest (@mostajs/auth — framework-agnostic)
  │
  ├─ extract X-API-Key from header / Bearer token / ?apikey=
  ├─ resolveApiKey (@mostajs/api-keys) — DB lookup + bcrypt verify
  ├─ isScopeAuthorized (@mostajs/api-keys) — check scope.values
  │     for each (scope, value) pair :
  │       checks: [{scope:'projects', value:slug},
  │                {scope:'operations', value:'read'|'write'|'admin'},
  │                {scope:'transports', value:'rest'|'mcp'|...}]
  ├─ touchApiKey — fire-and-forget : lastUsedAt, usageCount, lastIp
  │
  ▼
ormHandler (entité CRUD) ─→ sanitizer (strip password/hash/tokens)
  │
  ▼
HTTP Response

スコープベースの権限（汎用、拡張可能）

API キーの形状は次のとおりです：

{
  permissions: {
    scopes: {
      projects:   ['my-project','demo'] | '*',     // declared by @mostajs/mproject
      operations: ['read','write','admin'] | '*',  // declared by @mostajs/orm
      transports: ['rest','graphql','mcp'] | '*',  // declared by @mostajs/net
      // anything: any module can register a new scope
    },
    rateLimit: 500,
  }
}

@mostajs/api-keys は projects/operations/transports という名前を認識しません。これは意図的な設計です。各モジュールは起動時に registerScope(dialect, {name, label, …}) を使ってスコープを登録します。チェックは汎用的です：isScopeAuthorized(perms, scope, value)。

HTTP ステータスの対応

ケース	HTTP コード	本文
API キーなし	401	{error: {code:'UNAUTHORIZED', message:'API key required…'}}
API キーが無効／失効済み	401	{error: {code:'UNAUTHORIZED', message:'Invalid or revoked API key'}}
API キーは有効だがスコープ外	403	{error: {code:'FORBIDDEN', message:'API key not authorized for X="Y"'}}
API キーは有効	200/201	{status:'ok', data: …}（サニタイズ済み — パスワード／ハッシュなし）

MCP フォールバック（mcp.so との互換性）

/mcp エンドポイントでは、キーが提示されない場合、public-default というラベルの API キーへの自動フォールバックが許可されます。これにより、mcp.so／Claude Desktop との互換性が保たれます。公開キーはプロジェクト default のみで読み取り専用となるため、書き込みはブロックされます。

サニタイザー

password、hash、verifyToken、resetToken、apiKeyHash、secret、privateKey の各フィールドは、グローバルミドルウェアによってすべての JSON レスポンスから自動的に除去されます。/api/v1/User?limit=1 を通じて漏えいする心配はありません。

---

汎用スコープレジストリ

スコープのカタログは、ホストプロジェクトのデータベースに保存されます（JSON ファイルやハードコードされた定数は使用しません）。

-- Auto-créées au boot via @mostajs/api-keys
CREATE TABLE api_key_scopes (
  id, name, label, description, icon, cardinality,
  valuesSource ('static' | 'dynamic'), dynamicSourceRef
);

CREATE TABLE api_key_scope_values (
  id, scopeName, value, label, sortOrder, metadata
);

各モジュールは起動時にスコープを登録します。

import { registerScope } from '@mostajs/api-keys/server'

// Dans mosta-net/src/server.ts (boot)
await registerScope(dialect, {
  name: 'transports', label: 'Network transports',
  cardinality: 'low', valuesSource: 'static',
  staticValues: [
    {value:'rest', sortOrder:1},
    {value:'graphql', sortOrder:2},
    // … 9 more
  ],
})

await registerScope(dialect, {
  name: 'projects', label: 'Projects',
  cardinality: 'high', valuesSource: 'dynamic',
  dynamicSourceRef: 'Project.slug',  // queried at runtime
})

管理 UI は GET /api/api-keys/scopes を通じて動的なカタログを読み込み、マトリックスを表示します（@mostajs/api-keys/components/ の React コンポーネント ApiKeyScopeMatrix）。

---

マルチプロジェクト対応

@mostajs/mproject を利用します。同一サーバー上に、互いに分離されたデータベースを複数構成できます。

パスプレフィックス付きルート

# Default project (DB_DIALECT + SGBD_URI au boot)
curl http://localhost:4488/api/v1/User

# Project nommé 'analytics'
curl http://localhost:4488/api/v1/analytics/events

# Ou via header (équivalent)
curl http://localhost:4488/api/v1/events -H "X-Project: analytics"

実行中にプロジェクトを追加する

curl -X POST http://localhost:4488/api/projects \
  -H "X-API-Key: <admin-key>" \
  -d '{
    "name": "analytics",
    "dialect": "mongodb",
    "uri": "mongodb://localhost:27017/analytics",
    "schemas": [{"name":"Event", "fields":{"type":"string","ts":"date"}}]
  }'

projects-tree.json に保存されます（パス：MOSTA_PROJECTS 環境変数）。

---

クイックスタート（セルフホスト）

インストール

npm install @mostajs/net @mostajs/orm @mostajs/mproject \
            @mostajs/rbac @mostajs/auth @mostajs/api-keys \
            @mostajs/config better-sqlite3

SQLite で実行する（インフラ不要）

DB_DIALECT=sqlite \
SGBD_URI=./data/octonet.db \
DB_SCHEMA_STRATEGY=update \
[email protected] \
OCTONET_ADMIN_PASSWORD=ChangeMe123! \
npx mostajs-net serve

コンソール出力：

Loaded 3 schemas from schemas.json
[DAL:SQLite] INIT_SCHEMA strategy=update {"entities":["User","Product","Order"]}
✓ Apikey scopes registered (projects, operations, transports)
✓ RBAC ready — [email protected] trial=…  public=…
⚠ public demo apikey emitted ONCE → sk_live_xxxxxxxx…  (save it!)
✓ Sanitizer middleware on rest, graphql, ws, sse, trpc, mcp, odata, jsonrpc
✓ ApiKey middleware on rest, graphql, ws, sse, trpc, mcp, odata, jsonrpc
✓ Protected ormHandler ready (sanitizer + apikey global wrapper)
✓ T1 sandbox endpoint /try ready (rate-limited 10/h/IP, TTL 7d)

  @mostajs/net  v2.6.x
  ─────────────────────────────────────────────────
  Dialect:    sqlite (./data/octonet.db)
  Entities:   User, Product, Order  (3)
  Port:       4488
  Strategy:   update
  Transports: rest, graphql, ws, sse, trpc, mcp, odata, jsonrpc  (8)
  Ready.  3 entities × 8 transports = 24 endpoints

テスト

# Sans apikey → 401
curl http://localhost:4488/api/v1/User
# {"error":{"code":"UNAUTHORIZED","message":"API key required…"}}

# Avec apikey publique (depuis les logs ↑)
curl http://localhost:4488/api/v1/User -H "X-API-Key: sk_live_…"
# {"status":"ok","data":[{"id":"…","email":"[email protected]",…}]}  ← password absent

---

設定（.env）

データベース（必須）

DB_DIALECT=postgres                                # any of 13 dialects
SGBD_URI=postgresql://user:pass@localhost:5432/db
DB_SCHEMA_STRATEGY=update                          # 'update' (recommandé prod) | 'create' (drop+recreate, dev only)
DB_SHOW_SQL=false

システムダイアレクト（本番環境で推奨、任意）— v2.7.5+

システムデータベース（apikeys、RBAC ユーザー、監査、プラン、支払い、プロジェクトのライフサイクルメタデータ）を、変更可能なビジネスダイアレクトから分離します。これらの変数が設定されていない場合、ビジネスシングルトンへの透過的なエイリアスとなります（単一データベース構成との後方互換性）。

MOSTA_SYSTEM_DIALECT=postgres                       # any of 13 dialects
MOSTA_SYSTEM_URI=postgresql://user:pass@localhost:5432/octonet_system

背景と使用方法については、以下の「システムダイアレクト（ビジネスシングルトンから分離）」のセクションをご覧ください。

サーバー

MOSTA_NET_PORT=4488
MOSTA_PROJECTS=./projects-tree.json                # path to multi-project config
SCHEMAS_PATH=./schemas                              # directory scanning fallback

トランスポート（個別に切り替え可能）

MOSTA_NET_REST_ENABLED=true
MOSTA_NET_GRAPHQL_ENABLED=true
MOSTA_NET_WS_ENABLED=true
MOSTA_NET_SSE_ENABLED=true
MOSTA_NET_JSONRPC_ENABLED=true
MOSTA_NET_MCP_ENABLED=true
MOSTA_NET_TRPC_ENABLED=true
MOSTA_NET_ODATA_ENABLED=true
MOSTA_NET_GRPC_ENABLED=false
MOSTA_NET_NATS_ENABLED=false
MOSTA_NET_ARROW_ENABLED=false

MOSTA_NET_CORS_ORIGIN=*
MOSTA_RATE_LIMIT_CLIENT=1000

RBAC の初期設定（@mostajs/config 経由で読み込み — プロファイルのカスケード MOSTA_ENV=DEV に対応）

[email protected]               # 1er boot only ; ignored after
OCTONET_ADMIN_PASSWORD=secret-12345
OCTONET_ADMIN_FIRSTNAME=Admin                       # optional
OCTONET_ADMIN_LASTNAME=Octonet                      # optional
OCTONET_BOOTSTRAP_VERBOSE=false                     # detailed bootstrap logs
OCTONET_OPEN_MODE=false                             # dev only — passe sans apikey

T1 サンドボックス（任意）

OCTONET_TRIAL_DATA_DIR=./data/trials                # SQLite files per alias

クラウドミドルウェア（任意、将来対応 — Octocloud とメタデータ DB を共有）

OCTONET_META_URI=postgresql://user:pass@localhost:5432/octonet_meta   # shared meta DB
PORTAL_DB_URI=postgresql://user:pass@localhost:5432/octonet_cloud     # legacy octocloud DB

---

API エンドポイントのリファレンス

パブリック

エンドポイント	メソッド	認証	説明
/health	GET	オープン	サーバーのステータス、トランスポート、エンティティ
/try	GET	オープン	T1 サンドボックスを作成する HTML フォーム
/try	POST	オープン（IP あたり 10 回/時のレート制限）	サンドボックスを作成し、使い切りの apikey を返す
/api/v1/health	GET	オープン	API バージョン付きパスでのヘルスチェック

プロジェクト／エンティティの CRUD（apikey が必要）

エンドポイント	メソッド	操作	説明
/api/v1/{Entity}	GET	findAll	デフォルトプロジェクトのエンティティ一覧
/api/v1/{Entity}/:id	GET	findById	エンティティを 1 件取得
/api/v1/{Entity}/count	GET	count	件数を取得
/api/v1/{Entity}/one	GET	findOne	最初に一致したエンティティを取得
/api/v1/{Entity}/search	GET	search	テキスト検索
/api/v1/{Entity}	POST	create	挿入
/api/v1/{Entity}/:id	PUT	update	置換
/api/v1/{Entity}/:id	DELETE	delete	削除
/api/v1/{Entity}/:id/addToSet	POST	addToSet	配列に追加
/api/v1/{Entity}/:id/pull	POST	pull	配列から削除
/api/v1/{Entity}/:id/increment	POST	increment	数値を加算
/api/v1/{Entity}/upsert	POST	upsert	挿入または更新
/api/v1/{Entity}/aggregate	POST	aggregate	パイプライン
/api/v1/{Entity}/updateMany	POST	updateMany	一括更新
/api/v1/{Entity}/deleteMany	POST	deleteMany	一括削除
/api/v1/{project}/{Entity}/…	*	*	プロジェクトをスコープとする同じルート

スキーマ管理（管理者 apikey が必要）

エンドポイント	メソッド	説明
/api/upload-schemas-json	POST	実行時にスキーマを送信（再読み込みを実行）
/api/apply-schema	POST	スキーマ差分を適用
/api/compare-schema	POST	スキーマ差分をドライラン
/api/schemas-config	GET	現在登録されているスキーマ

認証と API キー（管理者権限が必要）

エンドポイント	メソッド	説明
/api/api-keys	GET / POST	キーの一覧表示／発行
/api/api-keys/:id	PUT / DELETE	更新／無効化
/api/api-keys/scopes	GET	登録済みスコープと値を一覧表示（管理者向けマトリックス UI 用）
/api/api-keys/scopes	POST	新しいスコープを登録（管理者）
/api/api-keys/scopes/:name/values	PUT / DELETE	スコープ値を管理

ネイティブトランスポート

エンドポイント	説明
/graphql	GraphQL エンドポイント + GraphiQL IDE
/ws	WebSocket 接続（エンティティイベント）
/events	SSE ストリーム
/rpc	JSON-RPC 2.0
/mcp	Model Context Protocol（Claude/Smithery など）
/trpc/{Entity}.{op}	tRPC プロシージャ
/odata/{Collection} · /odata/$metadata	OData v4

マルチプロジェクト管理

エンドポイント	メソッド	説明
/api/projects	GET	プロジェクトを一覧表示
/api/projects	POST	プロジェクトを追加
/api/projects/:name	PUT / DELETE	編集／削除

オブザーバビリティ

エンドポイント	説明
/api/performance	ライブメトリクス（req/s、p50、p99）
/api/config-tree	設定ツリー（インタラクティブ）
/api/live-log	ストリーミングログフィード

---

アーキテクチャ

                                 ┌──────────────────────────────────┐
                                 │       Fastify (port 4488)        │
                                 └────────────────┬─────────────────┘
                                                  │
       ┌─────────────────────────────────────────┴──────────────────────────────┐
       │                                                                        │
       ▼                                                                        ▼
┌────────────────────────┐                                       ┌────────────────────────┐
│  Transports (11)       │                                       │  Direct Fastify routes │
│  - REST                │                                       │  - /try                │
│  - GraphQL (mercurius) │                                       │  - /api/projects/*     │
│  - WS                  │                                       │  - /api/api-keys/*     │
│  - SSE                 │                                       │  - /health, /metrics   │
│  - JSON-RPC            │                                       └────────────────────────┘
│  - MCP (SDK Anthropic) │
│  - gRPC                │              ┌─────────────────────────────────────┐
│  - tRPC                │              │  Auth pipeline                      │
│  - OData               │              │  ┌──────────────┐                   │
│  - NATS                │              │  │ extractAuth  │ ←  HTTP request   │
│  - Arrow               ├──────────────┤  │ Context      │                   │
└────────────────────────┘              │  └──────┬───────┘                   │
                                        │         ▼                           │
                                        │  ┌──────────────┐                   │
                                        │  │ checkRequest │ ←  scope-checks   │
                                        │  │ (mosta-auth) │                   │
                                        │  └──────┬───────┘                   │
                                        │         ▼                           │
                                        │  ┌──────────────┐                   │
                                        │  │ checkApiKey  │ ←  resolve+verify │
                                        │  │ (api-keys)   │                   │
                                        │  └──────┬───────┘                   │
                                        └─────────┼───────────────────────────┘
                                                  ▼
                                        ┌────────────────────────┐
                                        │ Sanitizer middleware   │
                                        │ strips password/hash/  │
                                        │ tokens before response │
                                        └────────┬───────────────┘
                                                 ▼
                                        ┌────────────────────────┐
                                        │ ormHandler             │
                                        │ → ProjectManager.resolve│
                                        │ → EntityService.execute │
                                        └────────┬───────────────┘
                                                 ▼
                                        ┌────────────────────────┐
                                        │ @mostajs/orm dialect   │
                                        │ (13 SGBD)              │
                                        └────────────────────────┘

利用するエコシステムモジュール

モジュール	Octonet での役割
@mostajs/orm	永続化（13 dialects）
@mostajs/mproject	マルチプロジェクト管理（default + sandbox + サブスクライバー）
@mostajs/rbac	ID 管理（User、Role、Permission、Account）+ AccountSchema + OCTONET_RBAC_SEED
@mostajs/auth	フレームワークに依存しない checkRequest オーケストレーター、hashPassword
@mostajs/api-keys	apikey の CRUD + スコープ（Scope/ScopeValue schemas）+ checkApiKey + ApiKeyScopeMatrix 管理者 UI
@mostajs/config	MOSTA_ENV によるカスケード対応の環境変数ヘルパー
@mostajs/cloud-middleware	クォータ／サブスクリプション（オプション — Octocloud 接続時に有効）
@mostajs/replicator	CQRS マルチレプリカ（オプション）
@mostajs/project-life	Project 永続化スキーマ（オプション — JSON ではなく DB ストレージを使用する場合）

---

システム dialect（業務シングルトンとは分離）

v2.7.5 から利用可能 — 本番環境で確認された 「/api/change-dialect 後に apikey が見つからない」 バグを解決します。

dialect を 2 つに分ける理由

Octonet は、実行時に DB 接続を変更する管理者向けルート（/api/change-dialect、/api/reload-config、/api/reconnect）を公開しています。業務側では、これは正当な動作です（現在のプロジェクトの userland エンティティは、管理者のニーズに応じて postgres → sqlite → mongodb に移行できます）。

しかし、システムモジュール（apikey、RBAC users、audit、サブスクリプションプラン、payments、project-life metadata）は、これらの変更に追従しない安定したデータベースで稼働する必要があります。そうでない場合、業務 dialect の変更によって apikey が見つからなくなり、管理者は UI から締め出されます。

役割	環境変数	実行時に変更可能？	読み取り元
業務（userland エンティティ）	DB_DIALECT + SGBD_URI	はい（管理者 UI）	EntityService、トランスポート、データルート
システム（Octonet インフラ）	MOSTA_SYSTEM_DIALECT + MOSTA_SYSTEM_URI	いいえ（安定）	RBAC、apikey-middleware、account-scope、auth guards、sandbox /try

推奨設定（複数 DB の本番環境）

# Métier — peut bouger via /api/change-dialect
DB_DIALECT=postgres
SGBD_URI=postgresql://hmd:***@127.0.0.1:5432/octonet_business

# Système — stable, jamais touché par les routes admin
MOSTA_SYSTEM_DIALECT=postgres
MOSTA_SYSTEM_URI=postgresql://hmd:***@127.0.0.1:5432/octonet_system

単一 DB の設定（開発／シンプルなデプロイ）

MOSTA_SYSTEM_* を空のままにすると、自動的に業務シングルトンのエイリアスになります（後方互換性 100％、v2.7.5 より前と同じ動作）。

手順

1. 既存のデプロイを複数 DB モードに移行する

# 1. Sauvegarder la base actuelle
pg_dump octonet_business > backup-pre-split.sql

# 2. Créer la base système (vide — RBAC seed re-exécute au boot)
createdb octonet_system

# 3. Ajouter MOSTA_SYSTEM_* dans .env
echo 'MOSTA_SYSTEM_DIALECT=postgres' >> .env.local
echo 'MOSTA_SYSTEM_URI=postgresql://hmd:***@127.0.0.1:5432/octonet_system' >> .env.local

# 4. Restart Octonet — le bootstrap RBAC + scopes seed sur octonet_system
pm2 restart octonet-mcp

# 5. Restaurer les apikeys et RBAC users de l'ancienne base
#    (à scripter selon convention métier — typiquement export/import des
#    tables api_keys, users, roles, permissions, scopes, scope_values)

2. システムが業務から適切に分離されていることを確認する

# Avant /api/change-dialect : apikey doit fonctionner
curl -H "X-API-Key: sk_live_…" http://localhost:4488/api/auth/verify
# → 200 OK

# Bouger le dialect métier vers SQLite
curl -X POST -H "Content-Type: application/json" \
  -d '{"dialect":"sqlite","uri":":memory:","connect":true}' \
  http://localhost:4488/api/change-dialect
# → "Dialecte changé et connecté : sqlite"

# Re-tester l'apikey — DOIT toujours fonctionner (système intact)
curl -H "X-API-Key: sk_live_…" http://localhost:4488/api/auth/verify
# → 200 OK (bug résolu en v2.7.5)

v2.7.5 より前では、2 つ目の curl は 503 metadata DB unavailable または 401 PostgreSQL not connected. Call connect() first. を返していました。

3. アプリケーションコードからシステム dialect を読み取る

import { getSystemDialect } from '@mostajs/data-plug'

const sysDialect = await getSystemDialect()
// Utiliser comme un dialect normal pour requêter les tables système
// (apikeys, users, roles, audit_log, plans, etc.)

4. 起動時のブートストラップを確認する

octonet-mcpの起動時に、次の2つのログが表示されます。

✓ DB connectée: postgres                            ← métier
✓ System dialect: postgres (octonet_system)         ← système (si MOSTA_SYSTEM_* défini)
✓ RBAC ready — admin=… trial=… public=…             ← seed côté système
✓ ApiKey middleware on REST/SSE/GraphQL/...         ← câblé sur système

src/server.tsのシステム関連箇所 (参考)

18か所の呼び出し元で、ビジネス用シングルトンの代わりにgetSystemDialect()からダイアレクトを取得するようになりました。

ブロック	箇所数	呼び出し元
RBACのブートストラップ	1	bootstrapRbac(systemDialect, …)
スコープの登録	4	registerScope(systemDialect, …) × 3 + systemDialect.initSchema(scopeTables)
グローバルミドルウェア	2	createApiKeyMiddleware(() => systemDialect, …) + createAccountScopeMiddleware(() => systemDialect)
トランスポートごとのミドルウェア	2	各transport.use(…)に同様に適用
トランスポートの認証ガード	6	authGuard(systemDialect, …) × 6 (SSE、GraphQL、JSON-RPC、gRPC、tRPC、OData)
カスタムの/api/auth/verify	2	checkApiKey(systemDialect, …) + new UserRepository(systemDialect)
サンドボックス/try	2	registerTryRoutes({ dialect: systemDialect, … }) + startTrialCleanupJob({ dialect: systemDialect, … })

ビジネス用ダイアレクト*（dialect）*は、引き続き次の用途で正当に使用されます。

• ビジネス用シングルトンの初期ブートストラップ*（L98）* + pm.setDefault('default', dialect, …) （L126、L240）
• 管理ルート/api/reconnect、/api/change-dialect、/api/reload-config、/api/test-connection、/api/truncate-tables、/api/drop-tables — いずれも明示的にビジネス関連の操作です
• ユーザー領域のエンティティを提供するEntityService （保護されたトランスポート経由のCRUD操作）

作業の各ステップ (履歴)

ステップ	リポジトリ	成果物
1	@mostajs/data-plug v1.2.2-1.2.4 （APIgetSystemDialect + ORMファサード）	npm
2	@mostajs/net v2.7.5 （起動時のbootstrapSystemDialect）	git
3	@mostajs/api-keys 0.2.3、@mostajs/payment 0.4.1、@mostajs/project-life 0.1.3、@mostajs/subscriptions-plan 0.3.5 （WeakMapリポジトリ + ファサード）	npm
4	@mostajs/net v2.7.5 （利用側をgetSystemDialect()に切り替え — 18か所）	git
5	/api/change-dialectのpostgres → sqliteシナリオの統合テスト	⏳
6	amiaへのデプロイ + MOSTA_SYSTEM_URIのスモークテスト	⏳

---

起動シーケンス

1. @mostajs/config を介して .envを読み込みます（プロファイルのカスケード MOSTA_ENV）
2. メインの方言に接続します（SGBD_URI）
3. スキーマを読み込みます（優先順位：getAllSchemas() レジストリ → schemas.json → SCHEMAS_PATH ディレクトリのスキャン）
4. 戦略 update/create を使用して dialect.initSchema(schemas) を実行します
5. RBACをブートストラップします（octonet-rbac-bootstrap.ts）：
   • UserSchema/RoleSchema/PermissionSchema/PermissionCategorySchema/AccountSchema/ApiKeySchema を登録します
   • seedRBAC(OCTONET_RBAC_SEED) — 6カテゴリ、25権限、4ロール（admin/subscriber/trial/public）
   • OCTONET_ADMIN_EMAIL/PASSWORD から createAdmin() を実行します
   • Account trial-playground（type='trial'）を作成します
   • User public-demo（role=public）を作成します
   • Account public-system（type='system'）を作成します
   • default プロジェクトにスコープを限定した ApiKey public-default（読み取り専用、REST + MCP）を生成します — 平文で一度だけ出力されます
6. 正規スコープを登録します：projects（動的、Project.slug）、operations（静的：read/write/admin）、transports（静的：11個の値）
7. デフォルトプロジェクトを projects-tree.json に追加します（ownerId=admin、visibility=public）
8. projects-tree.json から追加のプロジェクトを読み込みます
9. ormHandler を composeMiddleware([sanitizer, apikey], ormHandler) でラップします → protectedOrmHandler
10. 有効な各トランスポートを起動します：
    • transport.use(loggingMiddleware)
    • transport.use(sanitizerMiddleware)
    • transport.use(apiKeyMiddleware)
    • transport.setHandler(ormHandler)
    • transport.start(config)
11. Fastifyルートを登録します：
    • registerDynamicRestRoutes(app, protectedOrmHandler, pm) — /api/v1/...
    • registerProjectRoutes(app, pm, protectedOrmHandler) — /:project/*
    • registerTryRoutes(app, {dialect, pm}) — /try POST
    • registerTryPage(app) — /try GET（HTML）
    • startTrialCleanupJob({dialect, pm}) — TTL 7日間の毎時cron
12. ポートでリッスンします（MOSTA_NET_PORT）

---

14言語対応のNetClient

Octonetは14種類のネイティブランタイムから利用でき、同じAPIキー、同じURLを使用できます：

ランタイム	パッケージ	レジストリ
Node/TS	@mostajs/net/client (built-in)	npm
Java	com.mostajs:mostajs-net-client	Maven Central
Java + Spring Boot	com.mostajs:mostajs-net-client-spring-boot-starter	Maven Central
.NET	MostaJs.Net.Client	NuGet
Python	mostajs-net-client	PyPI
Go	github.com/apolocine/mosta-net-client-go	pkg.go.dev
Swift	mosta-net-client-swift	Swift Package Index
Kotlin	io.github.apolocine:mostajs-net-client-kt	Maven Central
Dart / Flutter	mostajs_net_client	pub.dev
Rust	mostajs-net-client	crates.io
PHP	mostajs/net-client	Packagist
Ruby	mostajs-net-client	RubyGems
Elixir	mostajs_net_client	Hex.pm
Lua	mostajs-net-client	LuaRocks
Delphi	MostaJsNetClient	GetIt
Unity (C#)	com.mostajs.net-client	OpenUPM

モノレポ： github.com/apolocine/mosta-net-clients

各NetClientは同じAPI契約に従います：

NetClient.create()
  .url(...)
  .apiKey(...)
  .build()
  .findAll(entity, filter, options)
  .findById(entity, id)
  .create(entity, data)
  .update(entity, id, data)
  .delete(entity, id)
  .uploadSchemasJson(schemas)
  .health()

---

本番環境へのデプロイ（amia.fr）

リファレンスデプロイは、PostgreSQLバックエンドで octonet.amia.fr + mcp.amia.fr（互換エイリアス）上で稼働します：

URL	役割
https://octonet.amia.fr	Octonetサーバー（REST、MCP、GraphQL、WS、SSE、tRPC、OData、JSON-RPC）
https://mcp.amia.fr	互換性のためのDNSエイリアス — 旧mcp.so
https://octocloud.amia.fr	Octocloud — SaaSポータル Next.js（サブスクリプション、管理UI）

デプロイキット一式は Entreprise/octonet-mcp/ にあります：

• apache/mcp.amia.fr.conf — Apache2 vhost（SSEプロキシ、WSアップグレード、Let's Encrypt SAN証明書）
• ecosystem.config.cjs — PM2設定
• deploy.sh / install.sh / update.sh — オーケストレーションスクリプト
• tests/smoke-all.sh — スモークテスト一式（DNS、TLS、/health、SSE MCP、REST、/try、Java NetClient）

---

CLI

npx mostajs-net serve                      # Start server
npx mostajs-net mcp                        # MCP-only mode
npx mostajs-net generate-apikey <label>    # Émettre une apikey via CLI
npx mostajs-net hash-password <password>   # Hash bcrypt
npx mostajs-net info                       # JSON config dump

npx octonet-mcp --dialect=X --uri=Y        # Standalone MCP server (process séparé)

---

ライセンス

AGPL-3.0-or-later — 派生コードをオープンソースのままにする限り、自由に利用できます。 商用ライセンスもご利用いただけます：[email protected]。料金はプロジェクト単位で、シート単位ではありません。

— (c) 2026 Dr Hamid MADANI <[email protected]>