@pecot/tools-mcp 0.0.0-stage → 1.0.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "pecot-t",
+  "version": "1.0.1",
+  "description": "pecot-t（pecot-tools）— 許可リストで限定した CLI コマンドを MCP ツールとして提供するプラグイン",
+  "author": {
+    "name": "pecot"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kohei Hayakawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# @pecot/tools-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+pecot-tools プラグインの MCP サーバを、npm のパッケージとして単体で配布したものです。プラグインを導入していない環境でも、
+MCP クライアントに 1 エントリ登録するだけで pecot-tools のツールが使えます。
+
+公開するのは許可リストで限定した awscli コマンドだけです。許可リストに無いコマンド、S3 への
+アップロード方向の指定、Athena の変更系クエリは、awscli を起動する前に拒否します。
+
+## 前提
+
+- Node.js 24 系は 24.22.1 以上、26 系は 26.12.1 以上（脆弱性の修正を含まない版では起動しません）
+- awscli v2（2.22 以上）が PATH にあり、認証（SSO プロファイル等）が設定済みであること。
+  ツールは awscli をそのまま起動する。シェルで `aws sts get-caller-identity` が通る状態を前提にする
+- Windows ネイティブ環境は対象外です（Linux / macOS / WSL2 で使用してください）
+
+## 登録
+
+使用する MCP クライアントの設定に次の 1 エントリを追加します。
+
+```json
+{
+  "mcpServers": {
+    "pecot-tools": {
+      "command": "npx",
+      "args": ["-y", "@pecot/tools-mcp"]
+    }
+  }
+}
+```
+
+Windows の MCP クライアントから使う場合は WSL2 経由で起動します。
+
+```json
+{
+  "mcpServers": {
+    "pecot-tools": {
+      "command": "wsl",
+      "args": ["npx", "-y", "@pecot/tools-mcp"]
+    }
+  }
+}
+```
+
+WSL 内の npx が非ログインシェルの PATH に無い場合は、`args` を差し替えます。
+差し替え後は `"args": ["-e", "bash", "-lc", "npx -y @pecot/tools-mcp"]` です。
+
+版を固定するときは、`@pecot/tools-mcp@1.2.3` のように版を付けます。
+依存は `npm-shrinkwrap.json` で固定されているため、同じ版なら同じ依存が入ります。
+
+## 初回の操作
+
+SSO で認証するときは、開始と完了確認の 2 つのツールを順に呼びます。
+
+1. `aws_sso_login`（任意で `profile`）を呼ぶ。応答の `data` に `verificationUrl` と `userCode` が
+   返るので、URL をブラウザで開いてコードを入力し承認する
+2. `aws_sso_login_status`（同じ `profile`）を呼ぶ。`state` が `completed` になれば認証済み
+3. 以降は `aws_sts_get_caller_identity` 等の各ツールを同じ `profile` で呼ぶ
+
+開始から 10 分で `timed-out` になります。`timed-out` と `failed` のときは `aws_sso_login` を
+呼び直してください。
+
+## ツール
+
+| ツール | awscli | 種別 | 読取専用 | ページング |
+|---|---|---|---|---|
+| `aws_sso_login` | `sso login` | auth | false | - |
+| `aws_sso_login_status` | （子プロセス状態の参照） | auth | true | - |
+| `aws_sts_get_caller_identity` | `sts get-caller-identity` | read | true | - |
+| `aws_lambda_list_functions` | `lambda list-functions` | read | true | max-items |
+| `aws_lambda_get_function_configuration` | `lambda get-function-configuration` | read | true | - |
+| `aws_lambda_list_event_source_mappings` | `lambda list-event-source-mappings` | read | true | max-items |
+| `aws_logs_describe_log_groups` | `logs describe-log-groups` | read | true | max-items |
+| `aws_logs_describe_log_streams` | `logs describe-log-streams` | read | true | max-items |
+| `aws_logs_get_log_events` | `logs get-log-events` | read | true | limit / next-token |
+| `aws_logs_filter_log_events` | `logs filter-log-events` | read | true | max-items |
+| `aws_cloudwatch_get_metric_statistics` | `cloudwatch get-metric-statistics` | read | true | - |
+| `aws_sqs_list_queues` | `sqs list-queues` | read | true | max-items |
+| `aws_sqs_get_queue_attributes` | `sqs get-queue-attributes` | read | true | - |
+| `aws_athena_start_query_execution` | `athena start-query-execution` | execute | false | - |
+| `aws_athena_get_query_execution` | `athena get-query-execution` | read | true | - |
+| `aws_athena_get_query_results` | `athena get-query-results` | read | true | max-items |
+| `aws_s3_ls` | `s3 ls` | read | true | - |
+| `aws_s3_cp` | `s3 cp <s3_uri> <local_path>` | fetch | false | - |
+| `aws_s3api_get_object` | `s3api get-object` | fetch | false | - |
+| `aws_rds_describe_events` | `rds describe-events` | read | true | max-items |
+| `aws_rds_describe_db_clusters` | `rds describe-db-clusters` | read | true | max-items |
+| `aws_rds_describe_db_instances` | `rds describe-db-instances` | read | true | max-items |
+| `aws_scheduler_list_schedules` | `scheduler list-schedules` | read | true | max-items |
+| `aws_scheduler_get_schedule` | `scheduler get-schedule` | read | true | - |
+| `aws_ecr_describe_images` | `ecr describe-images` | read | true | max-items |
+| `aws_ec2_describe_instances` | `ec2 describe-instances` | read | true | max-items |
+
+全ツールが任意入力 `profile` と `region` を持ちます。指定したときだけ `--profile` / `--region` を
+付けて awscli を起動します。
+
+## 失敗したとき
+
+失敗した応答は `category` に理由の種別を持ちます。
+
+| category | 内容と対処 |
+|---|---|
+| `not-allowed` | 許可リストに無い操作。公開しているツールの範囲で実行する |
+| `invalid-input` | 入力が書式・制約に合わない。message の指摘に従って入力を直す |
+| `awscli-missing` | awscli が見つからない。awscli v2（2.22 以上）を導入して PATH を通す |
+| `auth-missing` | 認証設定が無い。`aws_sso_login` を実行するか `profile` を指定する |
+| `auth-expired` | 認証の有効期限切れ。`aws_sso_login` で再認証する |
+| `permission-denied` | 権限不足。`profile` と AWS 側のロール・許可セットを確認する |
+| `resource-not-found` | 対象が無い。名前とリージョンを確認する |
+| `timeout` | 時間切れ。取得範囲を狭めて再実行する |
+| `other` | 上記以外。応答の `stderr` を確認する |
+
+## 版
+
+npm の版は pecot-tools プラグインの版と一致します。

package/bin/pecot-tools-mcp.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+// 配布物は MCP サーバ専用エントリ。登録例が引数なしでも mcp として起動させる。
+if (process.argv.length === 2) process.argv.push('mcp')
+// 絶対パスの動的 import は Windows で ERR_UNSUPPORTED_ESM_URL_SCHEME になるため file URL を通す。
+const { main } = await import(pathToFileURL(path.join(root, 'cli/dist/cli.js')).href)
+main()

package/cli/dist/cli.d.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+export declare function createProgram(): Command;
+/**
+commander の既定である process.exit() 直呼びを止め、例外へ振り替える。
+サブコマンドを足したときに取りこぼさないよう再帰で適用する。
+*/
+export declare function applyExitOverrideRecursively(command: Command): void;
+export declare function main(nodeVersion?: string): void;
+//# sourceMappingURL=cli.d.ts.map

package/cli/dist/cli.js

@@ -0,0 +1,65 @@
+// pecot-tools CLI のエントリポイント。MCP サーバの起動 (`mcp`) だけを持つ薄い Command で、
+// MCP SDK の読み込みは action 内の dynamic import に閉じる。
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { Command, CommanderError } from 'commander';
+import { checkNodeRuntime } from './node-runtime.js';
+import { readVersion } from './version.js';
+export function createProgram() {
+    const program = new Command();
+    program.name('pecot-tools').version(readVersion());
+    const mcp = program
+        .command('mcp')
+        .description('MCP サーバとして stdio (stdin/stdout) で待ち受ける');
+    /* c8 ignore start -- action は dynamic import して実 process.stdin/stdout へ接続する。
+       単体テストから起動すると vitest worker の stdout ごと差し替えてしまう。
+       tests/e2e/mcp-stdio.test.ts が実プロセスの spawn で担保する。 */
+    mcp.action(async () => {
+        const { executeMcpServe, mcpServeDefaultDependencies } = await import('./mcp/serve.js');
+        executeMcpServe(mcpServeDefaultDependencies);
+    });
+    /* c8 ignore stop */
+    return program;
+}
+/**
+commander の既定である process.exit() 直呼びを止め、例外へ振り替える。
+サブコマンドを足したときに取りこぼさないよう再帰で適用する。
+*/
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- exitOverride() で変更する
+export function applyExitOverrideRecursively(command) {
+    command.exitOverride();
+    for (const child of command.commands)
+        applyExitOverrideRecursively(child);
+}
+export function main(nodeVersion = process.versions.node) {
+    const runtimeError = checkNodeRuntime(nodeVersion);
+    if (runtimeError !== undefined) {
+        process.stderr.write(`pecot-tools: ${runtimeError}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const program = createProgram();
+    applyExitOverrideRecursively(program);
+    try {
+        program.parse(process.argv);
+    }
+    catch (error) {
+        /* c8 ignore start -- commander 以外の例外は握り潰さずに再送出する */
+        if (!(error instanceof CommanderError))
+            throw error;
+        /* c8 ignore stop */
+        process.exitCode = error.exitCode === 0 ? 0 : 2;
+    }
+}
+/* v8 ignore start -- 直接起動時にだけ通る。挙動は tests/e2e/version.test.ts で担保 */
+if (process.argv[1] !== undefined) {
+    // import.meta.url は symlink を解決した実体パスを指すため、argv[1] 側も realpath に揃える。
+    // 揃えないと bin ラッパー等の symlink 経由起動で一致せず、何もせず exit 0 で終わる。
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- 起動された自分自身のパス
+    const selfUrl = pathToFileURL(realpathSync(process.argv[1])).href;
+    if (import.meta.url === selfUrl) {
+        main();
+    }
+}
+/* v8 ignore stop */
+//# sourceMappingURL=cli.js.map

package/cli/dist/domain/allowlist.d.ts

@@ -0,0 +1,228 @@
+/**
+失敗理由の種別（research R4）。
+*/
+export type FailureCategory = 'not-allowed' | 'invalid-input' | 'awscli-missing' | 'auth-missing' | 'auth-expired' | 'permission-denied' | 'resource-not-found' | 'timeout' | 'other';
+/**
+入力 1 項目の値の種類。検証規則と awscli 引数への写し方の双方を決める。
+
+`shorthand` だけは、利用者が直接指定する入力ではない。
+他の入力から `Key=value,Key=value` を組み立てる合成項目（`--query-execution-context` 等）。
+
+`shorthand-list` は、利用者がオブジェクトの配列で直接指定する入力。
+配列全体が `[{"Name":"…","Value":"…"}]` の JSON 1 トークンになる（`--dimensions` / `--filters` /
+`--image-ids`）。awscli はこれらのフラグを shorthand と JSON の双方で受ける。
+*/
+export type InputKind = 'string' | 'string-list' | 'integer' | 'boolean' | 'enum' | 'abs-path' | 's3-uri' | 's3-list-uri' | 'shorthand' | 'shorthand-list';
+/**
+`shorthand` の構成要素 1 件。同じエントリの入力 `from` の値を `key=<値>` として載せる。
+*/
+export interface ShorthandPart {
+    readonly key: string;
+    readonly from: string;
+}
+/**
+`shorthand-list` の要素が持てる構成要素 1 件。要素の `field` の値を JSON の `key` として載せる。
+
+`ShorthandPart.from` が「同じエントリの別入力」を指すのに対し、こちらは「配列要素の中の
+キー」を指す。意味が違うので型を分ける。`list` が true の構成要素は string[] を受け、
+JSON でも配列のまま載せる（`--filters` の `Values`）。
+*/
+export interface ShorthandElementPart {
+    readonly key: string;
+    readonly field: string;
+    readonly list?: boolean;
+}
+/**
+入力 1 項目の宣言。
+
+`awsFlag` を持つ項目は `--flag value`、`positional` を持つ項目は指定順の位置引数として渡す。
+どちらも持たない項目（`overwrite` 等）は検証だけに使い、awscli の引数には現れない。
+*/
+export interface InputSpec {
+    readonly name: string;
+    readonly kind: InputKind;
+    readonly required: boolean;
+    /**
+    `--log-group-name` のような awscli のオプション名。
+    */
+    readonly awsFlag?: string;
+    /**
+    位置引数の並び順（0 始まり）。
+    */
+    readonly positional?: number;
+    /**
+    未指定時に補う値。
+    */
+    readonly default?: string | number | boolean | readonly string[];
+    /**
+    kind が 'enum' のときの許容値。
+    */
+    readonly values?: readonly string[];
+    /**
+    kind が 'integer' のときの下限・上限（両端を含む）。
+    */
+    readonly min?: number;
+    readonly max?: number;
+    /**
+    kind が 'string' / 'string-list' のときの書式。
+    */
+    readonly pattern?: Readonly<RegExp>;
+    /**
+    kind が 'shorthand' のときの組み立て元。値を持つ構成要素だけが `,` 連結で並ぶ。
+    */
+    readonly parts?: readonly ShorthandPart[];
+    /**
+    kind が 'shorthand-list' のときの要素の構成。宣言外のキーは受け付けない。
+    */
+    readonly elements?: readonly ShorthandElementPart[];
+}
+/**
+公開を許可する awscli コマンド 1 件の静的定義（data-model.md の AllowlistEntry）。
+*/
+export interface AllowlistEntry {
+    readonly toolName: string;
+    readonly service: string;
+    readonly subcommand: string;
+    readonly kind: 'read' | 'fetch' | 'execute' | 'auth';
+    /**
+    `--output json` を付与するか（`s3 ls` / `s3 cp` は高レベルコマンドのため false）。
+    */
+    readonly jsonOutput: boolean;
+    readonly pagination: 'none' | 'max-items' | 'limit-next-token';
+    readonly inputs: readonly InputSpec[];
+    /**
+    同時指定を invalid-input にする入力名の組（例 log_stream_names と log_stream_name_prefix）。
+    */
+    readonly exclusive?: readonly (readonly string[])[];
+}
+/**
+`profile` の書式。data-model.md の `^[A-Za-z0-9_.-]+$` と同値（`\w` = `[A-Za-z0-9_]`）。
+
+inputSchema へ載せる mcp 層も同じ定数を読む。書式の定義をここ 1 箇所に保つため。
+*/
+export declare const PROFILE_PATTERN: RegExp;
+/**
+`region` の書式（`ap-northeast-1` 等）。
+
+先頭は 2〜4 文字。European Sovereign Cloud の `eusc-de-east-1` が 4 文字始まりで、
+2 文字固定だと入力検証エラーで弾かれる。
+契約書の共通規約も `^[a-z]{2,4}(-[a-z]+)+-\d$` で、本パターンと一致している。
+契約書は specs/012-awscli-mcp-server/contracts/mcp-tools.md を指す。
+*/
+export declare const REGION_PATTERN: RegExp;
+/**
+ISO 8601 の日時（`2026-09-01T00:00Z` / `2026-09-01T00:00:00.000+09:00`）。
+
+CloudWatch と RDS の timestamp 引数はこの書式で渡す。CloudWatch Logs 系の epoch ミリ秒
+（integer）とは型が異なるので、契約と description にも「ISO 8601」と明記している。
+`Z` とオフセット付きの双方を awscli 2.36.40 が正しく変換することを動作確認済み。
+*/
+export declare const TIMESTAMP_PATTERN: RegExp;
+/**
+全エントリ共通の任意入力 `profile`。
+*/
+export declare const PROFILE_INPUT: InputSpec;
+/**
+全エントリ共通の任意入力 `region`。
+*/
+export declare const REGION_INPUT: InputSpec;
+export declare const STS_GET_CALLER_IDENTITY: AllowlistEntry;
+export declare const LAMBDA_LIST_FUNCTIONS: AllowlistEntry;
+export declare const LAMBDA_GET_FUNCTION_CONFIGURATION: AllowlistEntry;
+/**
+`lambda list-event-source-mappings`。
+
+関数とイベントソース（SQS キュー等）の対応を引くために使う。`--event-source-arn` と
+`--function-name` は、片方だけでも両方でも指定できる。
+*/
+export declare const LAMBDA_LIST_EVENT_SOURCE_MAPPINGS: AllowlistEntry;
+export declare const LOGS_DESCRIBE_LOG_GROUPS: AllowlistEntry;
+export declare const LOGS_DESCRIBE_LOG_STREAMS: AllowlistEntry;
+export declare const LOGS_GET_LOG_EVENTS: AllowlistEntry;
+export declare const LOGS_FILTER_LOG_EVENTS: AllowlistEntry;
+/**
+CloudWatch の標準単位（`--unit` の候補。awscli 2.36.40）。
+
+許可リストの `values` と mcp 層の `z.enum`、契約テストが同じ配列を読む。3 箇所に写すと
+綴りがずれるので定義をここ 1 箇所に置く。`z.enum` は非空タプルを要求するため型注釈を付ける。
+*/
+export declare const CLOUDWATCH_UNIT_VALUES: readonly [string, ...string[]];
+/**
+`cloudwatch get-metric-statistics`。
+
+`--statistics` を必須にすることで `--extended-statistics`（パーセンタイル）を公開しない形に
+閉じている。API は双方の同時指定を拒否するため、片方だけを公開すれば足りる。
+*/
+export declare const CLOUDWATCH_GET_METRIC_STATISTICS: AllowlistEntry;
+export declare const SQS_LIST_QUEUES: AllowlistEntry;
+export declare const SQS_GET_QUEUE_ATTRIBUTES: AllowlistEntry;
+/**
+`athena start-query-execution`。
+
+`database` / `catalog` / `output_location` は検証だけに使う。
+awscli へは shorthand の `--query-execution-context` / `--result-configuration` として渡す。利用者に shorthand の
+文字列そのものを書かせると契約外のキー（`ExpectedBucketOwner` 等）を混ぜられるため、
+組み立てはここの宣言に閉じる。
+*/
+export declare const ATHENA_START_QUERY_EXECUTION: AllowlistEntry;
+export declare const ATHENA_GET_QUERY_EXECUTION: AllowlistEntry;
+export declare const ATHENA_GET_QUERY_RESULTS: AllowlistEntry;
+/**
+`s3 ls`。高レベルコマンドで JSON 出力を持たないため jsonOutput は false。
+*/
+export declare const S3_LS: AllowlistEntry;
+/**
+`s3 cp <s3_uri> <local_path>`。
+
+入力は「取得元は S3、書き出し先はローカル」の 2 項目に固定されている。
+そのため、アップロード方向は検証で弾くまでもなく表現できない（research R7）。
+*/
+export declare const S3_CP: AllowlistEntry;
+export declare const S3API_GET_OBJECT: AllowlistEntry;
+/**
+イベントを引ける発生元の種別（`--source-type` の候補。awscli 2.36.40）。
+
+許可リストの `values` と mcp 層の `z.enum`、契約テストが同じ配列を読む（`CLOUDWATCH_UNIT_VALUES`
+と同型）。
+*/
+export declare const RDS_SOURCE_TYPE_VALUES: readonly [string, ...string[]];
+/**
+`rds describe-events`。
+
+DB の停止・フェイルオーバー等のイベント履歴を引く。`--filters` は公開しない
+（API が受ける属性は版で動くので、契約に固定できる範囲へ絞る）。
+
+`duration`（現在から遡る分数）は `start_time` / `end_time` と意味が重なるので排他にする。
+*/
+export declare const RDS_DESCRIBE_EVENTS: AllowlistEntry;
+export declare const RDS_DESCRIBE_DB_CLUSTERS: AllowlistEntry;
+export declare const RDS_DESCRIBE_DB_INSTANCES: AllowlistEntry;
+export declare const SCHEDULER_LIST_SCHEDULES: AllowlistEntry;
+export declare const SCHEDULER_GET_SCHEDULE: AllowlistEntry;
+/**
+`ecr describe-images`。
+
+`tag_status` は awsFlag を持たない。shorthand の `--filter tagStatus=<値>` へ合成する
+（Athena の `query_execution_context` と同型）。`--filter` の `imageStatus` は公開しない
+ため、未指定時は API 既定の ACTIVE のイメージだけが返る。
+
+`image_ids` と `starting_token` は排他。ECR の API が `imageIds` 指定時に `nextToken` を
+受け付けない（botocore のサービスモデル）ため、構文としては通っても実行できない。
+*/
+export declare const ECR_DESCRIBE_IMAGES: AllowlistEntry;
+/**
+`ec2 describe-instances`。
+
+応答が大きくなりやすいので、description で max_items か filters による絞り込みを促している。
+`--dry-run` と `--include-managed-resources` は公開しない。
+*/
+export declare const EC2_DESCRIBE_INSTANCES: AllowlistEntry;
+/**
+公開するエントリの一覧。並びは契約表の順で、tools/list の並びもこれに従う。
+*/
+export declare const ALLOWLIST: readonly AllowlistEntry[];
+/**
+ツール名からエントリを引く。見つからなければ undefined（呼び出し側が not-allowed にする）。
+*/
+export declare function findAllowlistEntry(toolName: string, entries?: readonly AllowlistEntry[]): AllowlistEntry | undefined;
+//# sourceMappingURL=allowlist.d.ts.map