recordcrm

recordcrm

recordcrm は Attio CRM 用の小型クライアントです。自由形式のテキストまたは構造化フィルターでレコードを検索し、任意のオブジェクトにレコードを作成し、単一のレコードや属性の定義と選択肢を読み取り、会社および取引のレコードを作成・更新し、ワークスペースのリストとそのエントリーを一覧表示し、ワークスペースのメンバーを検索します。これらすべてを Attio API v2 経由で行います。

このパッケージはクリーンルームで再構築されたものであり、対象範囲を明記したコアサブセットです。元の Attio MCP サーバー向けにドキュメント化された19個の汎用操作のうち12個に加え、対象を限定した書き込み操作をカバーしています。対象外の操作は、以下の「対象範囲」に記載しています。

サービスとの通信方法

各ツールには Attio API トークンが必要です。

export ATTIO_API_KEY="your token"
# ATTIO_ACCESS_TOKEN is accepted as a fallback when ATTIO_API_KEY is unset.
# Optional override (default: https://api.attio.com/v2)
export ATTIO_API_URL="https://api.attio.com/v2"

トークンが設定されていない場合、リクエストを送信する前に、すべての呼び出しが ATTIO_API_KEY を示すエラーで失敗します。

ワイヤーフォーマットに関する注記： 元のプロジェクトの README にはツールとその用途が記載されています。ここに示すエンドポイントの形式は公開されている Attio API v2 に準拠し、再構成したものです。レコードは /v2/objects/{object}/records 配下にあります。レコード検索では、クエリが指定されている場合は full_text クエリー句を含めてレコードクエリーエンドポイント（.../records/query）に POST し、高度な検索では filter オブジェクトを使用します。書き込みでは、属性値を { "data": { "values": ... } } でラップします。属性の選択肢は、/v2/objects/{object}/attributes/{attribute} にある属性定義から読み取ります。レスポンスは JSON として解析され（成功時に本文が空の場合は { "status": "ok" } として読み取ります）、上流の HTTP エラーはステータスと本文のテキストを含めて報告されます。

インストール

npx @reneturcios/recordcrm records_search '{"object":"companies","query":"acme"}'

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/recordcrm

コンテナーはデフォルトで MCP サーバーを起動します。CLI として使用するには、CLI 引数を渡してください。

CLI

CLI はツールに対応しており、ツールごとに1つのサブコマンドが用意されています。引数は単一の JSON オブジェクトとして渡します。

recordcrm records_search '{"object":"companies","query":"acme","limit":5}'
recordcrm records_search_advanced '{"object":"companies","filters":{"name":{"$contains":"acme"}}}'
recordcrm records_create '{"object":"people","data":{"name":[{"value":"Ada"}]}}'
recordcrm records_get_info '{"object":"people","record_id":"..."}'
recordcrm lists_list '{}'
recordcrm --version

終了コード：成功時は 0、API エラーまたは検証エラー時（問題の内容を示します）は 1、使用方法のエラー時は 2 です。

MCP サーバー

1つのバイナリで両方の用途に対応します。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/recordcrm mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "recordcrm": {
      "command": "npx",
      "args": ["-y", "@reneturcios/recordcrm", "mcp"],
      "env": { "ATTIO_API_KEY": "your token" }
    }
  }
}

ツール

ツール	入力	機能
records_search	object（必須）、query、limit	自由形式のテキストクエリで、オブジェクト内のレコードを検索します。
records_search_advanced	object（必須）、filters（必須）、limit	構造化フィルターを使って、オブジェクト内のレコードを検索します。
records_create	object（必須）、data（必須）	属性値を使って、オブジェクトにレコードを作成します。
records_get_info	object（必須）、record_id（必須）	ID を指定して、オブジェクトからレコードを1件取得します。
records_get_attribute_options	object（必須）、attribute（必須）	選択肢を含む属性定義を取得します。
companies_create	data（必須）	属性値を使って会社のレコードを作成します。
companies_update	record_id（必須）、data（必須）	ID を指定して会社のレコードを更新します。
deals_create	data（必須）	属性値を使って取引のレコードを作成します。
deals_update	record_id（必須）、data（必須）	ID を指定して取引のレコードを更新します。
lists_list	—	ワークスペース内のすべてのリストを一覧表示します。
list_entries_list	list（必須）、limit	リスト内のエントリーを一覧表示します。
workspace_members_get	workspace_member_id（必須）	ID を指定してワークスペースメンバーを1人取得します。

対象範囲

このコアサブセットでは、records_search_by_relationship、 records_get_interactions、records_batch、汎用の records_update／records_delete操作、lists_create、 lists_update_configuration、list_entries_filter、 list_entries_manage、records_get_list_memberships、 diagnostics_get、および汎用のノート／タスク操作は省略しています。元の実装にあるフィールドマッピング設定も再現していません。このサブセットでは、属性値とフィルターをAttio APIの形式のまま直接受け渡します。検索結果、レコードの内容、リストデータは上流のAttioサービスが生成するものであり、このパッケージが再現するのはツールのインターフェースとリクエスト／レスポンスの処理であって、同サービスのデータではありません。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSEを参照してください。