Spedy NFS-e MCP

認証付きMCP Streamable HTTPエンドポイントを通じて、Spedy NFS-eの発行およびステータス操作を公開するInvokta Action Engineです。

このエンジンには3つのケイパビリティが含まれています：

• openapi.emitir-nfse: NFS-eを作成し、非同期発行のためにキューに登録します。

• openapi.consultar-nfse: 1件のNFS-eの現在のステータスを読み取ります。

• openapi.listar-nfse: Spedyのフィルタとページネーションを使用してNFS-eレコードを一覧表示します。

すべてのケイパビリティには認証済みプリンシパルが必要です。Spedyの認証情報はサーバー側に保持され、MCPツールの入力として受け付けられることはありません。

初回実行

npm run check
npm run build
npm run mcp:http

同梱のローカル設定は、http://127.0.0.1:3400/mcp でMCPを提供します。クライアントは Authorization: Bearer <MCP_BEARER_TOKEN> を送信する必要があります。

コミット済みの .env.example と無視されるローカルの .env にはモック値が含まれています。実際のリクエストを行う前に MCP_BEARER_TOKEN と SPEDY_API_KEY を置き換えてください。デフォルトのコネクタターゲットはSpedyのサンドボックスであり、本番環境が暗黙的に選択されることはありません。

Related MCP server: Receita Federal NFS-e: Notas Recebidas MCP

設定

発行は非同期です。emitir-nfse の成功結果は、Spedyがリクエストを受け入れ、キューに登録したことを意味します。認可または拒否を確認するには、consultar-nfse またはSpedyのWebhookを使用してください。再試行を冪等にするために、常に安定した integrationId を提供してください。

プロジェクト構成

• src/capabilities/ はドメインアクションと、その入力、出力、アクセス、実行コントラクトを管理します。

• src/engine.ts は安定したケイパビリティIDを登録し、エンジン所有の依存関係を提供します。

• src/direct.ts は最小の実行可能なスモークテストパスです。

• test/engine.test.ts は公開エンジン境界を通じて動作を検証します。

• AGENTS.md はプロジェクトの譲れないアーキテクチャと納品ルールを記録しています。

• .agents/skills/develop-invokta-project/SKILL.md は互換性のあるエージェントに完全な変更ワークフローを提供します。

生成されたケイパビリティのレビュー

1. AGENTS.md と生成された開発スキルを読んでください。

2. 必要なドメイン成果に対する失敗するエンジンレベルのテストを追加してください。

3. src/capabilities/ 配下のモジュールを更新または置き換え、そのリテラルなケイパビリティIDを src/engine.ts に登録してください。

4. 直接および生成されたアダプタのエントリポイントを同じエクスポートされたエンジンに維持してください。アダプタ内でケイパビリティハンドラを複製しないでください。

5. npm run check を実行し、デプロイ前にdevtoolsでケイパビリティを確認してください。

対話的に開発する

npm run devtools

エンジンをビルドし、Invokta devtoolsを起動します。通常は http://localhost:4100/ で実行されます。コマンドが出力するURLを開くと、ケイパビリティの閲覧、選択した実行パスを通じたスキーマシード済みJSONからの呼び出し、ライブ呼び出しトレースの追跡、テストIDの切り替え、ドクターレポートの閲覧ができます。ソースの変更は、ホストされたエンジンを自動的に再ビルドして再起動します。

読み取り専用のdevtools診断を実行するには：

npm run devtools:doctor

MCP HTTPの起動

npm run build
npm run mcp:http

サーバーをパッケージ化し、既存のエンドポイントをプローブするには：

npm run deploy:package
npm run deploy:probe -- --url https://engine.example/mcp

デプロイ前に、生成されたすべてのケイパビリティのドメイン上の意味とアクセスルールをレビューしてください。