agentwit 0.3.0__tar.gz → 0.5.0__tar.gz

{agentwit-0.3.0 → agentwit-0.5.0}/.claude/settings.local.json

@@ -11,7 +11,8 @@
       "Bash(pip index:*)",
       "Bash(git push:*)",
       "Bash(git tag:*)",
-      "Bash(python3:*)"
+      "Bash(python3:*)",
+      "Bash(pytest tests/ -v)"
     ]
   }
 }

agentwit-0.5.0/.github/mcp_spec_version.json

@@ -0,0 +1 @@
+{"tag": "2024-11-05", "last_checked": "2026-03-16T00:00:00Z"}

agentwit-0.5.0/.github/workflows/mcp_spec_watch.yml

@@ -0,0 +1,160 @@
+name: MCP Spec Watch
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+on:
+  schedule:
+    - cron: "0 0 1 * *"
+  workflow_dispatch:
+
+jobs:
+  check-spec:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install pytest pytest-asyncio httpx
+
+      - name: Install agentwit
+        run: pip install -e ".[dev]"
+
+      - name: Get latest MCP spec tag
+        id: latest
+        run: |
+          LATEST_TAG=$(curl -s https://api.github.com/repos/modelcontextprotocol/specification/tags \
+            | jq -r '.[0].name')
+          echo "tag=${LATEST_TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Read previous tag
+        id: previous
+        run: |
+          PREV_TAG=$(jq -r '.tag' .github/mcp_spec_version.json)
+          echo "tag=${PREV_TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Check for changes
+        id: changed
+        run: |
+          if [ "${{ steps.latest.outputs.tag }}" != "${{ steps.previous.outputs.tag }}" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Fetch CHANGELOG
+        if: steps.changed.outputs.changed == 'true'
+        id: changelog
+        run: |
+          CHANGELOG=$(curl -s \
+            "https://raw.githubusercontent.com/modelcontextprotocol/specification/${{ steps.latest.outputs.tag }}/CHANGELOG.md" \
+            | head -50 || echo "(no CHANGELOG)")
+          {
+            echo "content<<EOF"
+            echo "${CHANGELOG}"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Run tests
+        if: steps.changed.outputs.changed == 'true'
+        id: tests
+        run: |
+          if pytest tests/ -v; then
+            echo "passed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "passed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create GitHub Issue (tests passed)
+        if: steps.changed.outputs.changed == 'true' && steps.tests.outputs.passed == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `📋 MCP仕様変更検知: ${{ steps.latest.outputs.tag }}`,
+              body: [
+                `## MCP仕様が更新されました`,
+                ``,
+                `- **旧バージョン:** \`${{ steps.previous.outputs.tag }}\``,
+                `- **新バージョン:** \`${{ steps.latest.outputs.tag }}\``,
+                `- **テスト:** ✅ 全通過`,
+                ``,
+                `## CHANGELOG (先頭50行)`,
+                ``,
+                `\`\`\``,
+                `${{ steps.changelog.outputs.content }}`,
+                `\`\`\``,
+              ].join('\n'),
+              labels: ['mcp-spec-update'],
+            });
+
+      - name: Create GitHub Issue (tests failed)
+        if: steps.changed.outputs.changed == 'true' && steps.tests.outputs.passed == 'false'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `🚨 MCP仕様変更検知・テスト失敗: ${{ steps.latest.outputs.tag }}`,
+              body: [
+                `## MCP仕様が更新されましたが、テストが失敗しました`,
+                ``,
+                `- **旧バージョン:** \`${{ steps.previous.outputs.tag }}\``,
+                `- **新バージョン:** \`${{ steps.latest.outputs.tag }}\``,
+                `- **テスト:** ❌ 失敗`,
+                ``,
+                `## CHANGELOG (先頭50行)`,
+                ``,
+                `\`\`\``,
+                `${{ steps.changelog.outputs.content }}`,
+                `\`\`\``,
+                ``,
+                `対応が必要です。`,
+              ].join('\n'),
+              labels: ['mcp-spec-update', 'test-failure'],
+            });
+
+      - name: Discord notification
+        if: steps.changed.outputs.changed == 'true' && env.MCP_SPEC_WEBHOOK != ''
+        env:
+          MCP_SPEC_WEBHOOK: ${{ secrets.MCP_SPEC_WEBHOOK }}
+        run: |
+          if [ "${{ steps.tests.outputs.passed }}" = "true" ]; then
+            EMOJI="📋"
+            STATUS="テスト ✅ 通過"
+          else
+            EMOJI="🚨"
+            STATUS="テスト ❌ 失敗"
+          fi
+          curl -s -X POST "$MCP_SPEC_WEBHOOK" \
+            -H "Content-Type: application/json" \
+            -d "{\"content\": \"${EMOJI} MCP仕様変更検知: \`${{ steps.latest.outputs.tag }}\` (旧: \`${{ steps.previous.outputs.tag }}\`) ${STATUS}\"}"
+
+      - name: Update mcp_spec_version.json
+        if: steps.changed.outputs.changed == 'true'
+        run: |
+          NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          echo "{\"tag\": \"${{ steps.latest.outputs.tag }}\", \"last_checked\": \"${NOW}\"}" \
+            > .github/mcp_spec_version.json
+
+      - name: Commit updated spec version
+        if: steps.changed.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .github/mcp_spec_version.json
+          git commit -m "chore: update MCP spec version to ${{ steps.latest.outputs.tag }}"
+          git push

{agentwit-0.3.0 → agentwit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwit
-Version: 0.3.0
+Version: 0.5.0
 Summary: Transparent proxy witness for AI agent ↔ MCP server communications
 Project-URL: Homepage, https://github.com/tokotokokame/agentwit
 Project-URL: Repository, https://github.com/tokotokokame/agentwit
@@ -23,6 +23,7 @@ Classifier: Topic :: System :: Logging
 Requires-Python: >=3.10
 Requires-Dist: anyio>=4.3.0
 Requires-Dist: click>=8.1.0
+Requires-Dist: cryptography>=41.0.0
 Requires-Dist: fastapi>=0.111.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: uvicorn[standard]>=0.29.0
@@ -43,10 +44,13 @@ Description-Content-Type: text/markdown
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-48%20passing-brightgreen.svg)](#)
+[![Tests](https://img.shields.io/badge/tests-132%20passing-brightgreen.svg)](#)
+[![PyPI](https://img.shields.io/badge/PyPI-v0.3.0-orange.svg)](https://pypi.org/project/agentwit/)
 
 ## Articles
-- 📝 [AIエージェントの「証人」を作った——設計思想（Zenn）](https://zenn.dev/tokotokokame/articles/bba6a258a458a1)
+- 📝 [Why I built a "witness" for AI agents — design philosophy (Zenn)](https://zenn.dev/tokotokokame/articles/bba6a258a458a1)
+- 📝 [Practical guide: audit an MCP server in 5 minutes (Zenn)](https://zenn.dev/tokotokokame/articles/)
+- 📝 [From Witness to Inspector — how agentwit evolved (Zenn)](https://zenn.dev/tokotokokame/articles/)
 
 ## What is agentwit?
 
@@ -57,6 +61,9 @@ Unlike existing tools that act as **"guards"** (blocking suspicious traffic),
 agentwit acts as a **"witness"** — it never blocks, never interferes, but
 records everything with cryptographic chain integrity.
 
+**v0.3.0 adds MCP Inspector** — a desktop GUI for debugging MCP servers
+in real time, with audit logs unified with the CLI proxy.
+
 ## Guard vs. Witness
 
 | Tool         | Approach          | Blocks traffic | Tamper-proof log |
@@ -88,13 +95,10 @@ event_1:  session_chain = sha256(genesis_hash  +  hash(event_1))
       │
       ▼
 event_2:  session_chain = sha256(event_1_chain +  hash(event_2))
-      │
-      ▼
-     ...
 ```
 
-Any single-byte modification to any event breaks the entire chain from
-that point forward — making tampering immediately detectable.
+Any single-byte modification breaks the chain from that point forward —
+making tampering immediately detectable.
 
 ## Quick Start
 
@@ -102,6 +106,7 @@ that point forward — making tampering immediately detectable.
 
 ```bash
 pip install agentwit
+pip install agentwit[full]  # with LangChain integration
 ```
 
 ### 1. Start the witness proxy
@@ -115,7 +120,7 @@ agentwit proxy --target http://localhost:3000 --port 8765
 
 ### 2. Point your agent to the proxy
 
-```bash
+```
 # Before: http://localhost:3000
 # After:  http://localhost:8765
 # That's it. No other changes needed.
@@ -136,6 +141,64 @@ agentwit replay --session ./witness_logs/session_20260314_120000
 # Chain integrity: VALID
 ```
 
+## MCP Inspector GUI (v0.3.0)
+
+A desktop debugger for MCP servers. Built with Tauri + React.
+
+```
+Left panel   — server info + tool list (READ/WRITE/EXEC tags)
+Center panel — parameter editor + JSON response viewer
+Right panel  — History / Metrics / Compare tabs
+```
+
+### Launch
+
+```bash
+# From .deb package (Linux)
+sudo dpkg -i mcp-inspector_0.1.0_amd64.deb
+mcp-inspector
+
+# From source
+cd gui && npm install && npx tauri dev
+```
+
+### Connect to an MCP server
+
+```
+Transport: HTTP
+URL: http://localhost:3000/mcp
+```
+
+For a remote server over SSH:
+
+```bash
+ssh -fNL 3000:localhost:3000 your-server
+# then connect to http://localhost:3000/mcp
+```
+
+### Audit log integration
+
+Enable **"agentwit audit"** in the GUI header — all executions are
+written to `~/.agentwit/audit.jsonl` in the same format as the CLI proxy.
+
+```
+Development (GUI)  ─┐
+                     ├→ same audit.jsonl → agentwit report
+Production (proxy) ─┘
+```
+
+### MCP Inspector vs. existing tools
+
+| Feature              | Anthropic CLI | Postman | agentwit Inspector |
+|----------------------|:-------------:|:-------:|:------------------:|
+| GUI                  | ❌            | ✅      | ✅                 |
+| MCP-native           | ✅            | ❌      | ✅                 |
+| stdio support        | ✅            | ❌      | ✅                 |
+| audit log            | ❌            | ❌      | **✅**             |
+| cost tracking        | ❌            | ❌      | **✅**             |
+| session compare      | ❌            | limited | **✅**             |
+| local / offline      | ✅            | ✅      | ✅                 |
+
 ## Commands
 
 ```
@@ -152,6 +215,22 @@ agentwit diff    --session-a DIR --session-b DIR
 | `replay`  | Replay and verify chain integrity of a session |
 | `diff`    | Compare two sessions side by side              |
 
+### Webhook notifications
+
+```bash
+agentwit proxy --target http://localhost:3000 --port 8765 \
+  --webhook https://hooks.slack.com/services/xxx \
+  --webhook-on HIGH,CRITICAL
+```
+
+Slack and Discord are both supported (auto-detected from URL format).
+
+### stdio transport
+
+```bash
+agentwit proxy --stdio -- python my_mcp_server.py
+```
+
 ## Witness Log Format
 
 Each intercepted event is stored as one JSON line in `witness.jsonl`:
@@ -173,13 +252,8 @@ Each intercepted event is stored as one JSON line in `witness.jsonl`:
 }
 ```
 
-Events are appended to a JSONL file as they arrive — the proxy never
-buffers or delays the upstream response.
-
 ## Tamper Detection
 
-Modify any field in the log and agentwit detects it immediately:
-
 ```bash
 # Simulate tampering: change "actor" in event[0]
 python3 -c "
@@ -189,19 +263,25 @@ lines[0]=json.dumps(e)+'\n'; open('witness.jsonl','w').writelines(lines)
 "
 
 agentwit replay --session ./witness_logs/session_20260314_120000
-# Session: session_20260314_120000  (6 events)
 # Chain integrity: TAMPERED
 #   [event 0] FAIL - session_chain mismatch:
 #     expected '0fd4d24bcb3dab7d171e…'
 #     got      'a79a9e4cdb19795a521e…'
 ```
 
-## Use Cases
+## LangChain Integration
 
-- **Security engineers** auditing AI agent behavior in production
-- **Enterprise teams** requiring AI activity compliance logs
-- **AI researchers** reproducibly comparing agent sessions
-- **Penetration testers** documenting MCP tool usage as evidence
+```bash
+pip install agentwit[full]
+```
+
+```python
+from agentwit import AgentwitCallback
+
+callbacks = [AgentwitCallback(output="./audit.json")]
+
+agent.run("your task", callbacks=callbacks)
+```
 
 ## Python API
 
@@ -210,7 +290,7 @@ from agentwit import WitnessLogger, ChainManager
 
 # Direct logging (no proxy needed)
 logger = WitnessLogger(session_dir="./logs", actor="my-agent")
-event = logger.log_event(
+logger.log_event(
     action="tools/call",
     tool="bash",
     full_payload={"params": {"command": "ls"}, "result": {"stdout": "..."}}
@@ -223,10 +303,37 @@ results = chain.verify_chain(events)
 all_valid = all(r["valid"] for r in results)
 ```
 
+## Version History
+
+| Version | Date       | Highlights                                          |
+|---------|------------|-----------------------------------------------------|
+| v0.1.0  | 2026-03-14 | MVP: HTTP/SSE/stdio proxy, tamper-proof witness log |
+| v0.2.0  | 2026-03-15 | HTML/Markdown reports, timeline diff, LangChain, Slack/Discord |
+| v0.3.0  | 2026-03-16 | MCP Inspector GUI, unified audit log, standard MCP `/mcp` endpoint |
+
+## Use Cases
+
+- **Security engineers** — audit AI agent behavior with tamper-proof evidence
+- **Enterprise teams** — compliance logs for AI activity
+- **AI researchers** — reproducibly compare agent sessions
+- **Penetration testers** — document MCP tool usage as forensic evidence
+- **MCP developers** — debug servers with a GUI before deploying
+
+## Roadmap
+
+- [ ] MCP spec auto-tracking (monthly change detection + automated tests)
+- [ ] HTML report generation from GUI
+- [ ] stdio transport live testing
+- [ ] Windows build verification
+- [ ] GUI test coverage (Rust + React components)
+- [ ] Auto-reconnect on connection drop
+- [ ] OWASP LLM Top 10 mapping
+
 ## Requirements
 
 - Python 3.10+
 - FastAPI, uvicorn, httpx, click (installed automatically)
+- GUI: Node.js 18+, Rust 1.70+ (for building from source)
 
 ## License