Merge pull request #57 from harumiWeb/feat/edit-mcp

Feat/edit mcp

Author: harumiWeb

.agents/skills/codacy-issues-fetcher/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: codacy-issues-fetcher
+description: Retrieve and format Codacy analysis issues by running `scripts/codacy_issues.py` in the ExStruct workspace. Use when users ask to inspect repository or pull-request Codacy findings, filter by severity, or produce structured issue output for review and fix planning.
+---
+
+# Codacy Issues Fetcher
+
+Run `scripts/codacy_issues.py` as the primary interface to Codacy issue retrieval.
+Avoid reimplementing API calls unless the script itself must be changed.
+
+## Workflow
+
+1. Confirm prerequisites.
+- Run from repository root so `scripts/codacy_issues.py` is reachable.
+- Ensure `CODACY_API_TOKEN` is set and valid.
+- Prefer explicit `org` and `repo` if user provides them; otherwise rely on Git `origin` auto-detection.
+
+2. Choose scope and severity.
+- Repository scope: omit `--pr`.
+- Pull request scope: pass `--pr <number>`.
+- Severity filter (`--min-level`): `Error`, `High`, `Warning`, `Info`.
+- Provider (`--provider`): `gh`, `gl`, `bb` (default is effectively `gh`).
+
+3. Run one of the command patterns.
+
+```powershell
+# Repository issues (explicit target)
+python scripts/codacy_issues.py <org> <repo> --provider gh --min-level Warning
+
+# Pull request issues (explicit target)
+python scripts/codacy_issues.py <org> <repo> --pr <number> --provider gh --min-level Warning
+
+# Pull request issues (auto-detect org/repo from git origin)
+python scripts/codacy_issues.py --pr <number> --min-level Warning
+```
+
+4. Parse output JSON and respond with actionable summary.
+- Trust payload fields: `scope`, `organization`, `repository`, `pullRequest`, `minLevel`, `total`, `issues`.
+- `issues` entries are formatted as:
+  `<level> | <file_path>:<line_no> | <rule> | <category> | <message>`
+- Report high-severity findings first, then summarize counts.
+
+## Error Handling
+
+- `HTTP 401` / `Unauthorized`: token invalid or missing permissions. Ask user to set or refresh `CODACY_API_TOKEN`.
+- `CODACY_API_TOKEN is not set`: export the environment variable before retrying.
+- `Invalid --provider`: use only `gh`, `gl`, or `bb`.
+- Segment validation errors (`Invalid org/repo/pr`): sanitize input and rerun.
+
+## Output Policy
+
+- Return concise triage-ready results, not raw command logs.
+- Include the exact command you used when reproducibility matters.
+- If no issues match the selected `--min-level`, state that explicitly.

.agents/skills/codacy-issues-fetcher/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codacy Issues Fetcher"
+  short_description: "Run codacy_issues.py to fetch and triage Codacy findings"
+  default_prompt: "Use $codacy-issues-fetcher to collect Codacy issues for this repository or PR and summarize the highest-priority fixes."

.bandit

@@ -0,0 +1,2 @@
+[bandit]
+exclude_dirs = tests,benchmark

.codacy.yml

@@ -1,2 +1,3 @@
 exclude_paths:
   - "benchmark/**"
+  - "tests/**"

AGENTS.md

@@ -47,14 +47,10 @@ AI は必ず次のルールに従ってコードを生成してください。
 
 ### 2.4 import の順序
 
-```
-
 1. 標準ライブラリ
 2. サードパーティ
 3. exstruct 内のモジュール
 
-```
-
 ### 2.5 Docstring（Google スタイル）
 
 関数・クラスには必ず Docstring を付ける。
@@ -111,51 +107,7 @@ AI は必要であれば **禁止事項を回避するためにリファクタ
 
 ---
 
-# 5. AI に依頼するときの標準プロンプト（Developer Prompt）
-
-AI に実装依頼する際は、以下のフォーマットが推奨されます。
-
-```
-
-あなたは ExStruct のコア開発エンジニアです。
-mypy strict + Ruff check を完全に通過するコードのみ生成してください。
-
-遵守事項：
-
-- 型ヒント完全
-- 境界は BaseModel、内部は dataclass を返す
-- 1 関数 = 1 責務
-- import 順序厳守
-- Google スタイルの docstring
-- 外部ライブラリ（xlwings, pandas）は Any 扱い
-- 複雑度を抑えること
-- 必要に応じて補助関数を追加して良い
-
-出力は Python コードのみ。
-
-```
-
----
-
-# 6. AI にエラー修正を依頼する際のルール
-
-mypy / Ruff のエラーが出た場合、AI への指示は次のテンプレートを使用します：
-
-```
-
-以下は mypy / Ruff のエラーメッセージです。
-すべてのエラーが解消されるようにコードを修正してください。
-
-<エラー全文>
-
-```
-
-AI は差分修正タスクが得意なため、
-この方式が最も効率的かつ正確です。
-
----
-
-# 7. AI の責務外（人間が担当する領域）
+# 5. AI の責務外（人間が担当する領域）
 
 AI は以下の領域は担当しません。人間が判断します。
 
@@ -168,45 +120,17 @@ AI は以下の領域は担当しません。人間が判断します。
 
 ---
 
-# 8. AI を開発パイプラインと組み合わせる例
-
-推奨フロー：
-
-1. 人間：仕様を記述
-2. AI：コード生成（テンプレート＋ガイドラインに従う）
-3. 自動：`mypy strict` チェック
-4. 自動：`ruff check --fix`
-5. AI：エラー出たら修正
-6. 人間：レビューしてマージ
-
-このサイクルにより **高速 & 高品質の開発が可能** になります。
-
----
-
-# 9. 最終目標
-
-AI エージェントが ExStruct のコードを書く場合でも：
-
-- バグのない型安全なコード
-- 一貫したコーディングスタイル
-- 仕様の誤解を最小化した実装
-- 人間が安心してレビューできるコード
-
-を常に提供できるようにする。
-
-この AGENTS ガイドラインは
-**Codex / ChatGPT を“チームメンバー”として扱うための基盤** です。
-
----
-
-# 10. 各種仕様の確認
-
-AI エージェントは必要に応じて以下のドキュメントを参照して ExStruct の開発をする
+# 6. 遵守すべき作業手順
 
-- 処理アーキテクチャ: `docs/architecture/pipeline.md`
-- プロジェクトアーキテクチャ: `docs/contributors/architecture.md`
-- コーディングガイドライン: `docs/agents/CODING_GUIDELINES.md`
-- データモデル: `docs/agents/DATA_MODEL.md`
-- タスク: `docs/agents/TASKS.md`
+AI はコード生成前に以下の手順を必ず踏んでください。
 
-**以上。AI はこのガイドラインに従って ExStruct の開発に参加してください。**
+1. **要件の理解**：仕様書や設計資料を読み込み、要件を完全に理解する
+2. **設計の検討**：必要に応じて関数分割やモデル設計を検討する。
+3. **仕様の定義**: 要件に基づいて、関数の引数・戻り値の型を定義する。
+4. **タスクの割り当て**: 各タスクを明確に定義し、実装順序を決定する。
+5. **コード実装**: 上記の基準を守りながらコードを実装する。
+6. **コードレビュー**: 自動生成されたコードを自己レビューし、品質基準を満たしているか確認する。
+7. **テストコードの生成**: 必要に応じて、テストコードも生成する。
+8. **テストの実行**: 生成されたテストコードを実行し、期待通りの動作を確認する。
+9. **静的解析**: `uv run task precommit-run` を実行し、mypy / Ruff エラーがないことを確認する。
+10. **ドキュメントの更新**: 変更があれば、関連するドキュメントも更新する。

CHANGELOG.md

@@ -8,6 +8,21 @@ All notable changes to this project are documented in this file. This changelog
 
 - _No unreleased changes yet._
 
+## [0.4.4] - 2026-02-16
+
+### Added
+
+- Added an MVP of Excel editing for MCP via `exstruct_patch`, including atomic apply semantics and expanded operations: `set_range_values`, `fill_formula`, `set_value_if`, and `set_formula_if`.
+- Added direct A1-oriented MCP read tools for extracted JSON: `exstruct_read_range`, `exstruct_read_cells`, and `exstruct_read_formulas`.
+- Added patch safety/review options: `dry_run`, `return_inverse_ops`, `preflight_formula_check`, and `auto_formula`.
+
+### Changed
+
+- Improved `exstruct_patch` input compatibility: `ops` now accepts both object lists (recommended) and JSON object strings.
+- Enabled `alpha_col` support more broadly across extraction/read flows, and added `merged_ranges` output support for alpha-column mode.
+- Updated MCP documentation and chunking guidance, including clearer error messages and mode guidance.
+- Changed MCP default conflict policy to `overwrite` for output handling.
+
 ## [0.4.2] - 2026-01-23
 
 ### Changed

README.md

@@ -73,11 +73,13 @@ exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict re
 Available tools:
 
 - `exstruct_extract`
+- `exstruct_patch`
 - `exstruct_read_json_chunk`
 - `exstruct_validate_input`
 
 Notes:
 
+- In MCP, `exstruct_extract` defaults to `options.alpha_col=true` (column keys: `A`, `B`, ...). Set `options.alpha_col=false` for legacy 0-based numeric string keys.
 - Logs go to stderr (and optionally `--log-file`) to avoid contaminating stdio responses.
 - On Windows with Excel, standard/verbose can use COM for richer extraction. On non-Windows, COM is unavailable and extraction uses openpyxl-based fallbacks.
 

docs/README.en.md

@@ -73,11 +73,13 @@ exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict re
 Available tools:
 
 - `exstruct_extract`
+- `exstruct_patch`
 - `exstruct_read_json_chunk`
 - `exstruct_validate_input`
 
 Notes:
 
+- In MCP, `exstruct_extract` defaults to `options.alpha_col=true` (column keys: `A`, `B`, ...). Set `options.alpha_col=false` for legacy 0-based numeric string keys.
 - Logs go to stderr (and optionally `--log-file`) to avoid contaminating stdio responses.
 - On Windows with Excel, standard/verbose can use COM for richer extraction. On non-Windows, COM is unavailable and extraction uses openpyxl-based fallbacks.
 

docs/README.ja.md

@@ -70,9 +70,16 @@ exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict re
 利用可能なツール:
 
 - `exstruct_extract`
+- `exstruct_patch`
 - `exstruct_read_json_chunk`
+- `exstruct_read_range`
+- `exstruct_read_cells`
+- `exstruct_read_formulas`
 - `exstruct_validate_input`
 
+- `exstruct_read_range` / `exstruct_read_cells` / `exstruct_read_formulas` は v0.4.4 で追加され、MCPサーバー実装とテストに登録済みです。
+- MCPでは `exstruct_extract` の `options.alpha_col=true` が既定です（列キーは `A`, `B`, ...）。従来の0始まり数値キーが必要な場合は `options.alpha_col=false` を指定してください。
+
 注意点:
 
 - 標準入出力の応答を汚染しないよう、ログは標準エラー出力（およびオプションで`--log-file`で指定したファイル）に出力されます。