Itcons.app

Itcons.app MCP サーバー

AI アシスタントを Itcons.app に接続するための Model Context Protocol サーバーです。

Itcons.app は、作業報告書、作業指示書、プロジェクト、クライアント、ユーザー、および関連する業務リソースを管理するための業務運営プラットフォームです。日次報告、割り当て、タスクの追跡、サービスの実施を中心に、現場とオフィスのワークフローをデジタル化できるよう、チームを支援することを目的としています。

このパッケージは、次の 2 つのモードで実行できます。

• Codex、Claude Desktop、その他のローカル MCP ホストなどのクライアント向けのローカル stdio モード。
• ChatGPT Apps などのホスト型 MCP クライアントや、公開 HTTPS MCP エンドポイントを必要とするその他のクライアント向けのリモート HTTP モード。

この MCP サーバーを使用すると、アシスタントは Itcons.app のデータを照会し、作業報告書や作業指示書を検索し、ステータス、ユーザー、リソース、プロジェクト、クライアントなどの業務カタログを一覧表示できます。また、設定されたユーザーに権限がある場合は、対応する Itcons.app レコードを作成できます。

機能

• POST /api/login_check で認証します。
• Itcons.app API 呼び出しに Bearer 認証を使用します。
• ITCONS_DOMAIN から API のベース URL を解決します。
• ステータス、ユーザー、リソース、クライアント、プロジェクト、作業指示書の種類、作業報告書のモデルを一覧表示します。
• 作業報告書と作業指示書を検索します。
• クライアント、プロジェクト、ユーザー、作業指示書を作成します。

この MCP サーバーには、意図的に Webhook を含めていません。リモート HTTP モードは MCP クライアントの通信向けであり、Itcons.app からの Webhook 配信を受信するためのものではありません。

インストール

npm からインストールする場合：

npm install -g @itcons-app/mcp

このリポジトリからインストールする場合：

npm install
npm run check

Node を Homebrew でインストールしていて、node／npm が PATH にない場合は、次を使用してください。

/opt/homebrew/opt/node/bin/npm install
/opt/homebrew/opt/node/bin/npm run check

設定

ローカルの stdio サーバーは、環境変数から Itcons.app の認証情報を読み取ります。

ITCONS_DOMAIN=demo
[email protected]
ITCONS_PASSWORD=change-me
ITCONS_TIMEZONE=Europe/Madrid

https://demo.itcons.app の場合は、次のように設定します。

ITCONS_DOMAIN=demo

ユーザー名とパスワードの代わりに、既存の Bearer トークンを使用することもできます。

ITCONS_DOMAIN=demo
ITCONS_TOKEN=ey...

ITCONS_API_BASE_URL は省略可能です。省略した場合、サーバーは次を使用します。

https://ITCONS_DOMAIN.itcons.app/api

MCP クライアントの設定例

グローバルにインストールしたパッケージを使用する設定例：

{
  "mcpServers": {
    "itcons-app": {
      "command": "itcons-app-mcp",
      "env": {
        "ITCONS_DOMAIN": "demo",
        "ITCONS_USERNAME": "[email protected]",
        "ITCONS_PASSWORD": "change-me",
        "ITCONS_TIMEZONE": "Europe/Madrid"
      }
    }
  }
}

リモート HTTP サーバー

リモート MCP サーバーを起動します。

PORT=3000 \
HOST=127.0.0.1 \
ITCONS_MCP_PUBLIC_URL=https://mcp.example.com \
ITCONS_OAUTH_CLIENT_ID=itcons-app-chatgpt \
ITCONS_OAUTH_CLIENT_SECRET=change-me \
npm run start:http

リモートサーバーは、次のエンドポイントを公開します。

• MCP Streamable HTTP エンドポイント：https://mcp.example.com/mcp
• 公開 ChatGPT アプリ向けのレポート専用 MCP エンドポイント：https://mcp.example.com/reports-mcp
• SSE 互換エンドポイント：https://mcp.example.com/sse
• OAuth 認可 URL：https://mcp.example.com/oauth/authorize
• OAuth トークン URL：https://mcp.example.com/oauth/token
• OAuth 動的クライアント登録 URL：https://mcp.example.com/oauth/register
• ヘルスチェック：https://mcp.example.com/health

ChatGPT の「Create app」画面では、公開 MCP URL を使用してください。

https://mcp.example.com/mcp

作業報告書だけに特化した、対象を絞った公開アプリには、次を使用してください。

https://mcp.example.com/reports-mcp

クライアントから特に SSE URL を求められた場合は、次を使用してください。

https://mcp.example.com/sse

ユーザーがアプリに接続すると、OAuth ログインページで Itcons.app のメールアドレスとパスワードを求められます。ITCONS_DOMAIN_LOOKUP_URL が設定されている場合、ページはメールアドレスから Itcons.app のドメインの検出を試みます。設定されていない場合、ユーザーはドメインを手動で入力できます。サーバーは Itcons.app で認証情報を検証し、後続の MCP 呼び出しに備えてメモリ上にセッショントークンを保存します。

ローカルのチェックアウトを使用する設定例：

{
  "mcpServers": {
    "itcons-app": {
      "command": "node",
      "args": [
        "/absolute/path/to/itcons-app-mcp/src/index.js"
      ],
      "env": {
        "ITCONS_DOMAIN": "demo",
        "ITCONS_USERNAME": "[email protected]",
        "ITCONS_PASSWORD": "change-me",
        "ITCONS_TIMEZONE": "Europe/Madrid"
      }
    }
  }
}

ツール

読み取り専用ツール：

• itcons_check_connection
• itcons_list_workorder_types
• itcons_list_work_report_models
• itcons_list_projects
• itcons_list_clients
• itcons_list_statuses
• itcons_list_users
• itcons_list_resources
• itcons_search_workorders
• itcons_list_pending_workorders
• itcons_search_work_reports
• itcons_list_work_reports_by_date
• itcons_list_today_work_reports

作成ツール：

• itcons_create_workorder
• itcons_create_user
• itcons_create_project
• itcons_create_client

/reports-mcp で公開されるレポート専用プロファイルのツール：

• itcons_check_connection
• itcons_list_work_report_models
• itcons_search_work_reports
• itcons_list_work_reports_by_date
• itcons_list_today_work_reports

ツールのアノテーション：

• 読み取り専用ツールは、非公開の Itcons.app データを読み取るだけのため、readOnlyHint: true、destructiveHint: false、openWorldHint: false を設定します。
• 作成ツールは、非公開の Itcons.app ワークスペース内でのみレコードを作成し、公開インターネット上には公開しないため、readOnlyHint: false、destructiveHint: false、openWorldHint: false を設定します。

環境変数

変数	必須	説明
ITCONS_DOMAIN	はい	インストール先のサブドメインです。https://demo.itcons.app の場合は、demo を使用します。
ITCONS_USERNAME	ITCONS_TOKEN が設定されていない場合は必須	Itcons.app のユーザー名またはメールアドレスです。
ITCONS_PASSWORD	ITCONS_TOKEN が設定されていない場合は必須	Itcons.app のパスワードです。
ITCONS_TOKEN	いいえ	既存の Bearer トークンです。設定されている場合、ログインはスキップされます。
ITCONS_API_BASE_URL	いいえ	代替 API ベース URL です。
ITCONS_TIMEZONE	いいえ	itcons_list_today_work_reports で使用するタイムゾーンです。デフォルトは Europe/Madrid です。
PORT	いいえ	HTTP サーバーのポートです。デフォルトは 3000 です。
HOST	いいえ	HTTP サーバーのバインド先ホストです。デフォルトは 127.0.0.1 です。
ITCONS_MCP_PUBLIC_URL	リモートモードでは必須	HTTPS の公開オリジンです。例：https://mcp.example.com。
ITCONS_MCP_PATH	いいえ	リモート MCP エンドポイントのパスです。デフォルトは /mcp です。
ITCONS_MCP_SSE_PATH	いいえ	SSE 互換エンドポイントのパスです。デフォルトは /sse です。
ITCONS_MCP_ALLOWED_HOSTS	リモートモードでは推奨	許可する Host ヘッダーをカンマ区切りで指定します。例：mcp.example.com。
ITCONS_OAUTH_CLIENT_ID	いいえ	リモートサーバーが想定する OAuth クライアント ID です。デフォルトは itcons-app-chatgpt です。
ITCONS_OAUTH_CLIENT_SECRET	リモートモードでは推奨	リモートサーバーが想定する OAuth クライアントシークレットです。
ITCONS_OAUTH_CLIENTS_FILE	公開アプリでは推奨	動的に登録された OAuth クライアントの永続化に使用する JSON ファイルです。
ITCONS_DOMAIN_LOOKUP_URL	いいえ	メールアドレスから Itcons.app のドメインを検出するためのエンドポイントです。デフォルトは https://auto.itcons.app/webhook/my-domain です。
ITCONS_HTTP_AUTH_DISABLED	いいえ	ローカル HTTP スモークテストの場合に限り、1 を設定します。リモート MCP の Bearer 認証を無効にします。

注意事項

• 作業指示の保留ステータスは 4 です。
• itcons_search_workorders は /workorders を取得し、ローカルでフィルターを適用します。
• itcons_list_work_reports_by_date は、/2.0/partes が返す date フィールドでフィルターします。
• itcons_create_workorder は status: 4 と isArchived: 0 を送信します。
• itcons_create_user は、現在の API に合わせて /2.0/users に配列ペイロードを送信します。
• itcons_create_client は /clients に配列ペイロードを送信し、該当する場合は配列の最初の項目を返します。

開発

構文チェックを実行します：

npm run check

ローカル MCP ディスカバリーのスモークテストを実行します：

npm run smoke

ローカル HTTP MCP のスモークテストを実行します：

npm run smoke:http

Itcons.app に対するライブ読み取り専用 HTTP スモークテストを実行します：

ITCONS_DOMAIN=demo \
[email protected] \
ITCONS_PASSWORD=change-me \
npm run smoke:http:live

ChatGPT 形式の接続をシミュレートするライブ OAuth スモークテストを実行します：

ITCONS_DOMAIN=demo \
[email protected] \
ITCONS_PASSWORD=change-me \
npm run smoke:oauth:live

Itcons.app に対するライブ読み取り専用スモークテストを実行します：

ITCONS_DOMAIN=demo \
[email protected] \
ITCONS_PASSWORD=change-me \
npm run smoke:live

公開 npm パッケージを公開します：

npm publish --access public

セキュリティ

.env ファイルや実際の認証情報をコミットしないでください。このパッケージは、npm への公開時に .env、node_modules、デバッグログを除外します。

作成ツールは Itcons.app に実際の変更を書き込みます。MCP クライアントによる変更が許可されている認証情報とインストール環境でのみ使用してください。

組み込みのリモート OAuth 実装は、認証コードとアクセストークンをメモリ内に保存します。初回デプロイでは単一の Node.js プロセスを使用するか、複数のレプリカを起動する前に、メモリ内のマップを Redis などの永続ストレージに置き換えてください。