teeshield 0.1.0__tar.gz

teeshield-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+      - name: Verify CLI
+        run: teeshield --version

teeshield-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

teeshield-0.1.0/.github/workflows/scan.yml

@@ -0,0 +1,55 @@
+name: TeeShield Scan
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'MCP server path or GitHub URL to scan'
+        required: true
+        type: string
+      format:
+        description: 'Output format'
+        required: false
+        default: 'table'
+        type: choice
+        options:
+          - table
+          - json
+
+  # Can be called from other repos
+  workflow_call:
+    inputs:
+      target:
+        description: 'MCP server path to scan'
+        required: true
+        type: string
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install TeeShield
+        run: pip install -e .
+
+      - name: Run scan
+        run: |
+          teeshield scan "${{ inputs.target }}" --format "${{ inputs.format || 'table' }}"
+
+      - name: Run scan (JSON artifact)
+        if: always()
+        run: |
+          teeshield scan "${{ inputs.target }}" --format json -o scan-report.json || true
+
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: teeshield-report
+          path: scan-report.json

teeshield-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.env
+.env.*
+*.log
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+node_modules/
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+reports/
+
+# Test targets (cloned repos)
+test-targets/
+
+# Generated reports
+*.report.json
+fs-report.json

teeshield-0.1.0/CURATION-REPORT.md

@@ -0,0 +1,68 @@
+# TeeShield Curation Report
+
+Batch scan of top MCP servers. Generated by `teeshield scan`.
+
+## Summary
+
+| Server | Tools | Security | Description | Arch | Overall | Rating | Rewrite Gain |
+|--------|-------|----------|-------------|------|---------|--------|-------------|
+| filesystem (official) | 14 | 10.0 | 3.2 | 10.0 | 7.6 | B | +4.8 |
+| memory (official) | 9 | 10.0 | 2.3 | 10.0 | 7.3 | B | - |
+| git (official) | 12 | 10.0 | 2.4 | 10.0 | 7.3 | B | +6.6 |
+| fetch (official) | 1 | 9.0 | 3.5 | 10.0 | 7.3 | B | - |
+| time (official) | 0 | 10.0 | 5.0 | 10.0 | 8.2 | A | - |
+| everything (python-sdk) | 13 | 10.0 | 2.8 | 7.0 | 6.7 | B | - |
+| supabase (community) | 30 | 9.0 | 2.3 | 8.0 | 6.4 | B | +5.6 |
+
+**Totals:** 7 servers, 79 tools scanned
+
+## Key Findings
+
+### 1. Description quality is universally poor
+- Average description score: **3.1/10**
+- 0% of tools have scenario triggers ("Use when...")
+- 0% of tools have parameter examples
+- <5% have error guidance
+- This confirms the Neon finding: tool descriptions are the #1 bottleneck for agent tool selection
+
+### 2. Rewriting delivers massive gains
+
+**Template-based (zero cost):**
+- filesystem: 3.7 -> 8.5 (+4.8 points)
+- git: 2.9 -> 9.5 (+6.6 points)
+- supabase: 3.4 -> 9.0 (+5.6 points)
+- Average improvement: +5.7 points
+
+**Claude API (higher quality):**
+- filesystem: 3.7 -> 9.6 (+5.9 points)
+- memory: 3.4 -> 9.4 (+6.0 points)
+- git: 2.9 -> 8.6 (+5.7 points)
+- fetch: 3.5 -> 9.6 (+6.1 points)
+- **Average improvement: +5.9 points with Claude API**
+
+### 3. Security is generally solid
+- Average security score: **9.7/10**
+- Official servers score 10.0 (clean)
+- Community servers have minor issues (SSRF in fetch, credential handling)
+- No critical vulnerabilities found in production servers
+
+### 4. Architecture quality varies
+- Official servers: strong (10.0) - tests, error handling, types
+- Community servers: moderate (7-8) - often missing tests
+
+## Top Curation Candidates
+
+Servers that would benefit most from TeeShield curation (high tool count + low description quality):
+
+1. **supabase** - 30 tools, desc 2.3/10, improvement potential +5.6
+2. **filesystem** - 14 tools, desc 3.2/10, improvement potential +4.8
+3. **everything** - 13 tools, desc 2.8/10
+4. **git** - 12 tools, desc 2.4/10, improvement potential +6.6
+5. **memory** - 9 tools, desc 2.3/10
+
+## Not Yet Scanned (need pattern support)
+- Playwright MCP (compiled JS only, no source TS)
+- GitHub MCP (Go, not yet supported)
+- Context7 (clone failed)
+- AWS MCP servers
+- Desktop Commander

teeshield-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentShield
+
+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.

teeshield-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: teeshield
+Version: 0.1.0
+Summary: Scan, improve, and certify MCP servers and AI agent skills
+Author: TeeShield
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,mcp,security,skill-rating,tool-firewall
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.40; extra == 'ai'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TeeShield — Security Scanner for MCP tools
+
+Scan, rate, and harden MCP servers for AI agent safety.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+# Scan an MCP server
+teeshield scan ./path/to/server.py
+
+# Rewrite tool descriptions (requires ANTHROPIC_API_KEY)
+teeshield rewrite ./path/to/server.py --dry-run
+
+# Harden a server (detect + fix security issues)
+teeshield harden ./path/to/server.py
+
+# Evaluate tool selection accuracy before/after
+teeshield eval ./original.py ./improved.py
+```
+
+## Rating Scale
+
+| Rating | Score | Meaning |
+|--------|-------|---------|
+| A+     | 9.0+  | Production-ready, fully certified |
+| A      | 8.0+  | Safe with minor suggestions |
+| B      | 6.0+  | Usable, needs improvements |
+| C      | 4.0+  | Significant issues found |
+| F      | <4.0  | Unsafe, do not deploy |
+
+## License
+
+MIT

teeshield-0.1.0/README.md

@@ -0,0 +1,39 @@
+# TeeShield — Security Scanner for MCP tools
+
+Scan, rate, and harden MCP servers for AI agent safety.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+# Scan an MCP server
+teeshield scan ./path/to/server.py
+
+# Rewrite tool descriptions (requires ANTHROPIC_API_KEY)
+teeshield rewrite ./path/to/server.py --dry-run
+
+# Harden a server (detect + fix security issues)
+teeshield harden ./path/to/server.py
+
+# Evaluate tool selection accuracy before/after
+teeshield eval ./original.py ./improved.py
+```
+
+## Rating Scale
+
+| Rating | Score | Meaning |
+|--------|-------|---------|
+| A+     | 9.0+  | Production-ready, fully certified |
+| A      | 8.0+  | Safe with minor suggestions |
+| B      | 6.0+  | Usable, needs improvements |
+| C      | 4.0+  | Significant issues found |
+| F      | <4.0  | Unsafe, do not deploy |
+
+## License
+
+MIT

teeshield-0.1.0/action.yml

@@ -0,0 +1,65 @@
+name: 'TeeShield Scan'
+description: 'Scan an MCP server for security issues, description quality, and architecture'
+branding:
+  icon: 'shield'
+  color: 'blue'
+
+inputs:
+  target:
+    description: 'Path to MCP server directory'
+    required: true
+    default: '.'
+  fail-below:
+    description: 'Fail if overall score is below this threshold (0-10)'
+    required: false
+    default: '0'
+  format:
+    description: 'Output format (table or json)'
+    required: false
+    default: 'table'
+
+outputs:
+  score:
+    description: 'Overall scan score (0-10)'
+    value: ${{ steps.scan.outputs.score }}
+  rating:
+    description: 'Rating (F/C/B/A/A+)'
+    value: ${{ steps.scan.outputs.rating }}
+  tool-count:
+    description: 'Number of tools detected'
+    value: ${{ steps.scan.outputs.tool_count }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install TeeShield
+      shell: bash
+      run: pip install teeshield
+
+    - name: Run scan
+      id: scan
+      shell: bash
+      run: |
+        teeshield scan "${{ inputs.target }}" --format "${{ inputs.format }}"
+
+        # Parse JSON for outputs
+        REPORT=$(teeshield scan "${{ inputs.target }}" --format json 2>/dev/null)
+        echo "score=$(echo "$REPORT" | python -c 'import sys,json; print(json.loads(sys.stdin.read(), strict=False)["overall_score"])')" >> $GITHUB_OUTPUT
+        echo "rating=$(echo "$REPORT" | python -c 'import sys,json; print(json.loads(sys.stdin.read(), strict=False)["rating"])')" >> $GITHUB_OUTPUT
+        echo "tool_count=$(echo "$REPORT" | python -c 'import sys,json; print(json.loads(sys.stdin.read(), strict=False)["tool_count"])')" >> $GITHUB_OUTPUT
+
+    - name: Check threshold
+      if: inputs.fail-below != '0'
+      shell: bash
+      run: |
+        SCORE="${{ steps.scan.outputs.score }}"
+        THRESHOLD="${{ inputs.fail-below }}"
+        if (( $(echo "$SCORE < $THRESHOLD" | bc -l) )); then
+          echo "::error::TeeShield score $SCORE is below threshold $THRESHOLD"
+          exit 1
+        fi

teeshield-0.1.0/batch-rewrites/rewrite-fetch.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": "fetch",
+    "original": "Fetches a URL from the internet and optionally extracts its contents as markdown.\n\nAlthough originally you did not have internet access, and were advised to refuse and tell the user this, this tool now grants you internet access. Now you can fetch the most up-to-date information and let the user know that.",
+    "rewritten": "Fetch content from any URL on the internet and convert it to readable markdown format.\n\nUse when the user wants to access current web content, read articles, check documentation, retrieve data from APIs, or get up-to-date information from websites. This tool provides you with internet access to fetch the latest information.\n\nKey parameters:\n- url: The web address to fetch (e.g., \"https://example.com\", \"https://api.github.com/repos/owner/repo\")\n- extract_contents: Boolean flag to convert HTML to clean markdown (default: true for better readability)\n\nCommon errors and handling:\n- Invalid URLs: Ensure proper format with http:// or https://\n- Blocked content: Some sites may restrict access or require authentication\n- Large files: Tool may timeout on very large responses\n- Network issues: Retry if initial fetch fails\n\nThis tool automatically converts web pages to markdown for easier reading and analysis. The markdown extraction removes clutter like ads and navigation, focusing on main content. Use this for any web-based information retrieval task where you need current, live data rather than your training knowledge."
+  }
+]

teeshield-0.1.0/batch-rewrites/rewrite-git.json

@@ -0,0 +1,62 @@
+[
+  {
+    "name": "git_status",
+    "original": "Shows the working tree status",
+    "rewritten": "Query the current state of the Git working directory and staging area. Use when the user wants to see which files are modified, staged, untracked, or have merge conflicts.\n\nThis tool shows:\n- Modified files (red in terminal)\n- Staged files ready for commit (green in terminal) \n- Untracked files not yet added to Git\n- Files with merge conflicts\n- Current branch information\n\nUse this BEFORE other Git operations to understand what changes exist. For example, check status before running git_add to see which files need staging, or before git_commit to verify what will be committed.\n\nUnlike git_diff tools that show actual content changes, git_status only shows which files have changed. Use git_diff_unstaged to see unstaged changes, git_diff_staged for staged changes, or git_diff for any specific comparison.\n\nThe tool requires no parameters and works from any directory within a Git repository. If run outside a Git repository, it will return an error indicating no Git repository was found."
+  },
+  {
+    "name": "git_diff_unstaged",
+    "original": "Shows changes in the working directory that are not yet staged",
+    "rewritten": "Show unstaged changes in the working directory that haven't been added to the staging area yet. Use when the user wants to review modifications before staging them, see what files have been changed, or understand the diff between the current working state and the last commit.\n\nThis command reveals local edits that exist only in your working directory - changes you've made but haven't yet prepared for commit with `git add`. Perfect for reviewing your work before staging, checking if you've made unintended modifications, or understanding what's different from the committed state.\n\nReturns unified diff format showing additions (+), deletions (-), and modified lines with context. If no unstaged changes exist, returns empty output.\n\n**When to use this vs similar tools:**\n- Use `git_diff_unstaged` for working directory changes not yet staged\n- Use `git_diff_staged` for changes already added but not committed  \n- Use `git_diff` for comparing specific commits or branches\n- Use `git_status` for a high-level overview without detailed diffs\n\nCommon scenario: After editing files, run this to see exactly what you've changed before deciding what to stage with `git_add`."
+  },
+  {
+    "name": "git_diff_staged",
+    "original": "Shows changes that are staged for commit",
+    "rewritten": "Show the differences between staged files and the last commit. Use when the user wants to review changes before committing, verify what will be included in the next commit, or check staged modifications.\n\nThis displays only files added to the staging area with `git add`. If no changes are staged, returns empty output. Common scenarios include reviewing code before commit, checking if specific files were properly staged, or comparing staged content against the current HEAD.\n\nUse this instead of `git_diff_unstaged` (shows unstaged working directory changes) or `git_diff` (shows differences between any two references). If you need to see all changes (staged + unstaged), run both tools separately.\n\nReturns unified diff format showing additions (+), deletions (-), and context lines. If the repository has no commits yet, compares against an empty tree."
+  },
+  {
+    "name": "git_diff",
+    "original": "Shows differences between branches or commits",
+    "rewritten": "Shows differences between specific branches, commits, or tags in a Git repository. Use when the user wants to compare code changes between two specific references, view what changed in a particular commit, or see differences between branches before merging.\n\n**Parameters:**\n- `from_ref`: Source reference (e.g., \"main\", \"HEAD~1\", \"abc123f\", \"v1.0\")\n- `to_ref`: Target reference (e.g., \"feature-branch\", \"HEAD\", \"def456a\")\n- `file_path`: Optional specific file to compare\n\n**Examples:**\n- Compare branches: `from_ref=\"main\"`, `to_ref=\"feature-auth\"`\n- View commit changes: `from_ref=\"HEAD~1\"`, `to_ref=\"HEAD\"`\n- Check tag differences: `from_ref=\"v1.0\"`, `to_ref=\"v1.1\"`\n\n**Use THIS tool when:** Comparing two specific Git references. Use `git_diff_staged` for staged changes, `git_diff_unstaged` for working directory changes, or `git_show` to view a single commit's details.\n\n**Common errors:** Invalid reference names will show an error - verify refs exist using `git_branch` or `git_log` first."
+  },
+  {
+    "name": "git_commit",
+    "original": "Records changes to the repository",
+    "rewritten": "Record changes to the repository by creating a commit with a descriptive message.\n\nUse when the user wants to save their staged changes permanently to the Git history, typically after using git_add to stage files. This creates a snapshot of the current staged changes.\n\n**Parameters:**\n- `message`: Commit message describing the changes (e.g., \"Fix user authentication bug\", \"Add password validation feature\", \"Update documentation for API endpoints\")\n\n**Common workflow:** First use git_status to see changed files, git_add to stage desired changes, then git_commit to record them. If no files are staged, the commit will fail - use git_add first.\n\n**Error handling:** If commit fails due to no staged changes, check git_status and stage files with git_add. For empty commit messages, provide a descriptive message explaining what changed and why.\n\n**vs other tools:** Use git_add before this to stage changes, git_status to check what will be committed, and git_log after to view the new commit. Unlike git_show which displays existing commits, this creates new ones."
+  },
+  {
+    "name": "git_add",
+    "original": "Adds file contents to the staging area",
+    "rewritten": "Stage files for the next commit by adding them to Git's staging area. Use when the user wants to prepare specific files or changes for committing, such as after making edits, creating new files, or selectively staging modifications.\n\nProvide file paths as parameters - use \".\" to stage all changes, specific filenames like \"src/main.py\", or glob patterns like \"*.js\". For new files, you must add them before they can be committed. For modified files, adding stages the current version.\n\nCommon scenarios: Stage all changes with \".\", stage specific files with exact paths, or stage by file type using patterns. If files aren't found, verify paths are relative to repository root.\n\nUse git_add (this tool) when preparing files for commit. Use git_status first to see which files need staging. Use git_diff_unstaged to review changes before staging, or git_diff_staged to see what's already staged. After staging, use git_commit to finalize changes. Use git_reset to unstage files if needed."
+  },
+  {
+    "name": "git_reset",
+    "original": "Unstages all staged changes",
+    "rewritten": "Reset staged changes back to unstaged state, clearing the Git index while preserving working directory changes.\n\nUse when the user wants to undo staging operations, remove files from the index before committing, or cancel a partial commit preparation. This is the Git equivalent of \"git reset\" without arguments.\n\n**Key scenarios:**\n- User accidentally staged wrong files with git_add\n- User wants to re-organize which changes go into different commits\n- User needs to unstage everything to start fresh with selective staging\n\n**Important distinctions:**\n- Use git_reset when you want to unstage ALL currently staged changes\n- Use git_diff_staged first to see what will be unstaged\n- Unlike git_checkout, this doesn't modify file contents - only the staging area\n- Files remain modified in working directory; use git_status afterward to confirm\n\n**Common workflow:** Check git_status \u2192 Review git_diff_staged \u2192 Use git_reset \u2192 Re-add specific files with git_add\n\nThis tool affects the entire staging area at once. For examining what's currently staged before resetting, combine with git_diff_staged. After resetting, changes remain in working directory as unstaged modifications."
+  },
+  {
+    "name": "git_log",
+    "original": "Shows the commit logs",
+    "rewritten": "Query commit history and view detailed log information for a Git repository. Use when the user wants to see past commits, review project history, find specific changes, or investigate when features were added.\n\nDisplays commit messages, authors, dates, and SHA hashes in chronological order. Supports filtering by author, date ranges, file paths, and commit count limits.\n\nParameter examples:\n- max_count: 10 (show last 10 commits)\n- author: \"john@example.com\" (commits by specific author)\n- since: \"2024-01-01\" (commits after date)\n- path: \"src/main.py\" (commits affecting specific file)\n\nCommon errors: Invalid date formats or non-existent file paths will return empty results. Very large repositories may need max_count limits for performance.\n\nUse git_log for viewing commit history vs git_show for detailed content of a specific commit, git_status for current working directory state, or git_diff for comparing changes between commits/branches."
+  },
+  {
+    "name": "git_create_branch",
+    "original": "Creates a new branch from an optional base branch",
+    "rewritten": "Create a new Git branch from the current branch or a specified base branch. Use when the user wants to start new feature development, create experimental branches, or isolate work from the main codebase.\n\nRequires a branch name (e.g., \"feature/user-auth\", \"bugfix/login-error\", \"dev/new-api\"). Optionally specify a base branch to branch from (e.g., \"main\", \"develop\", \"v2.1\"). If no base is provided, branches from the currently checked-out branch.\n\nCommon usage patterns:\n- `git_create_branch` with name \"feature/payment-system\" (branches from current)\n- `git_create_branch` with name \"hotfix/security-patch\" and base \"main\"\n\nHandle errors gracefully: branch names with invalid characters will fail, and branching from non-existent base branches returns an error. Branch creation does not automatically switch to the new branch.\n\nUse this instead of `git_checkout` when you only need to create a branch without switching to it. Use `git_branch` to list existing branches or `git_checkout` to switch between branches after creation."
+  },
+  {
+    "name": "git_checkout",
+    "original": "Switches branches",
+    "rewritten": "Switch to an existing Git branch or restore files to their last committed state. Use when the user wants to change their working branch, discard uncommitted changes to specific files, or revert files to a previous state.\n\nFor branch switching, provide the branch name (e.g., \"main\", \"feature/login\", \"dev\"). For file restoration, specify file paths (e.g., \"src/app.js\", \"*.py\" for patterns).\n\nCommon errors include switching to non-existent branches (use git_branch to list available branches first) or having uncommitted changes that conflict (use git_status to check, then git_add + git_commit or git_reset to resolve).\n\nUnlike git_create_branch which creates new branches, git_checkout only switches to existing ones. Unlike git_reset which affects the entire working directory, git_checkout can target specific files. Use git_status before checkout operations to understand your current state."
+  },
+  {
+    "name": "git_show",
+    "original": "Shows the contents of a commit",
+    "rewritten": "Show the detailed contents and metadata of a specific git commit, including changed files, commit message, author, and date. Use when the user wants to examine what changes were made in a particular commit, review commit details, or investigate the history of specific modifications.\n\nProvide the commit hash (e.g., \"abc123f\", \"HEAD\", \"main~2\") as the primary parameter. Full hashes, short hashes, and git references are all supported. You can also specify additional options like --stat for summary statistics or --name-only for just filenames.\n\nCommon errors include invalid commit hashes (verify with git_log first) and commits that don't exist in the current branch. If a hash is ambiguous, git will prompt for clarification.\n\nUse git_show vs other tools: Choose git_show for examining completed commits, git_diff for comparing working directory changes, git_diff_staged for reviewing staged changes before committing, and git_log for browsing commit history without detailed content. git_show is ideal when you need both the commit metadata AND the actual code changes in one comprehensive view."
+  },
+  {
+    "name": "git_branch",
+    "original": "List Git branches",
+    "rewritten": "List all Git branches in the repository, showing both local and remote branches with their tracking relationships.\n\nUse when the user wants to see available branches, check which branch is currently active, or understand the branch structure before switching branches or creating new ones.\n\nShows branches with indicators: \"*\" marks the current branch, local branches appear without prefixes, and remote branches display with \"remotes/\" prefix. Also displays tracking relationships between local and remote branches.\n\nIf the command fails, ensure you're in a valid Git repository. Empty repositories with no commits won't show any branches until the first commit is made.\n\nUse this tool instead of git_status when you specifically need branch information rather than working directory status. Use before git_checkout to see available branches, or before git_create_branch to avoid naming conflicts. Complements git_log when you need to understand branch history and relationships."
+  }
+]

teeshield-0.1.0/batch-rewrites/rewrite-memory.json

@@ -0,0 +1,47 @@
+[
+  {
+    "name": "create_entities",
+    "original": "Create multiple new entities in the knowledge graph",
+    "rewritten": "Create multiple new entities simultaneously in the knowledge graph. Use when the user wants to add several related or unrelated entities at once, such as creating a set of people, locations, or concepts that will be interconnected later.\n\nProvide entities as an array where each entity includes:\n- name: unique identifier (e.g., \"John Smith\", \"Paris\", \"Machine Learning\")\n- entityType: category like \"Person\", \"Location\", \"Concept\", \"Organization\"\n- observations: optional array of descriptive facts\n\nExample: Creating entities for a business scenario - CEO, company, and headquarters location in one operation rather than individual create calls.\n\nCommon errors: Duplicate entity names will fail - ensure uniqueness across the entire graph. Empty names or invalid entityType values cause rejection.\n\nUse this instead of multiple individual entity creation calls when you have a batch of entities to add. Use create_relations afterward to connect these entities. For single entities, individual creation might be more appropriate. For adding descriptive information to existing entities, use add_observations instead."
+  },
+  {
+    "name": "create_relations",
+    "original": "Create multiple new relations between entities in the knowledge graph. Relations should be in active voice",
+    "rewritten": "Create multiple new relations between entities in the knowledge graph using active voice statements. Use when the user wants to establish connections, relationships, or associations between existing entities.\n\nRelations must be expressed in active voice format where the subject performs an action on the object (e.g., \"Alice works at Google\", \"Python supports object-oriented programming\", \"The meeting occurs on Monday\").\n\n**Parameter Examples:**\n- Subject: \"Tesla\", Relation: \"manufactures\", Object: \"electric vehicles\"\n- Subject: \"Shakespeare\", Relation: \"wrote\", Object: \"Hamlet\"\n- Subject: \"Database\", Relation: \"stores\", Object: \"customer records\"\n\n**Common Errors:** Ensure both subject and object entities already exist in the graph before creating relations. Avoid passive voice constructions like \"was created by\" - use \"created\" instead.\n\n**When to Use This vs Other Tools:**\n- Use `create_entities` first if the entities don't exist yet\n- Use `add_observations` to attach descriptive properties to single entities\n- Use `search_nodes` to verify entities exist before relating them\n- This tool specifically handles entity-to-entity connections, not entity attributes"
+  },
+  {
+    "name": "add_observations",
+    "original": "Add new observations to existing entities in the knowledge graph",
+    "rewritten": "Add new observations to existing entities in the knowledge graph. Use when the user wants to attach additional facts, properties, or descriptive information to entities that already exist in the graph.\n\nProvide the entity name exactly as it appears in the graph and include specific, factual observations. For example: entity \"John Smith\" with observations like \"works at Microsoft\", \"born in 1985\", or \"lives in Seattle\". Each observation should be a complete, standalone fact about the entity.\n\nCommon errors include referencing non-existent entities (use search_nodes first to verify) or adding vague observations like \"is good\" instead of specific facts like \"has 10 years experience in software engineering\".\n\nUse this tool instead of create_entities when the entity already exists and you only need to add more information. If the entity doesn't exist yet, use create_entities first. For connecting entities to each other, use create_relations instead of adding relational observations.\n\nThe tool will validate that the target entity exists before adding observations. If the entity is not found, search for it first or create it using create_entities."
+  },
+  {
+    "name": "delete_entities",
+    "original": "Delete multiple entities and their associated relations from the knowledge graph",
+    "rewritten": "Delete multiple entities and their associated relations from the knowledge graph. Use when the user wants to remove outdated information, clean up duplicate entries, or purge entire concept clusters from their knowledge base.\n\nRequires entity IDs as parameters - these are the unique identifiers returned by search_nodes or read_graph operations. Example: [\"person_123\", \"company_456\", \"event_789\"]. This operation cascades automatically, removing all relations where these entities participate as either source or target.\n\nCommon errors occur when providing invalid entity IDs or attempting to delete non-existent entities - the tool will skip invalid IDs and continue with valid ones. Always verify entity existence using search_nodes before deletion if unsure.\n\nChoose this over delete_relations when you want to remove entire concepts rather than just their connections. Use delete_observations for removing specific factual claims while keeping the entities intact. For surgical removal of single relationships, use delete_relations instead.\n\nWarning: This operation is irreversible and will permanently remove entities and all their associated data from the knowledge graph."
+  },
+  {
+    "name": "delete_observations",
+    "original": "Delete specific observations from entities in the knowledge graph",
+    "rewritten": "Delete specific observations from entities in the knowledge graph. Use when the user wants to remove outdated, incorrect, or unwanted observation data from existing entities while preserving the entities themselves.\n\nProvide the entity identifier and specify which observations to remove. For example, use entity_id=\"person_123\" and observation_key=\"age\" to remove age data, or observation_key=\"location\" to delete location information. You can target specific observation types like demographics, preferences, or historical data points.\n\nCommon errors include attempting to delete from non-existent entities (returns entity not found) or referencing invalid observation keys (returns key not found). Handle gracefully by verifying entity existence first using read_graph or search_nodes.\n\nUse delete_observations when you need surgical removal of specific data points. Choose delete_entities for complete entity removal, or delete_relations for removing connections between entities. This tool maintains entity structure while cleaning specific observation data, making it ideal for data correction, privacy compliance, or information updates without losing the underlying entity relationships."
+  },
+  {
+    "name": "delete_relations",
+    "original": "Delete multiple relations from the knowledge graph",
+    "rewritten": "Delete multiple relations from the knowledge graph by specifying relation IDs. Use when the user wants to remove connections between entities, clean up incorrect relationships, or bulk delete outdated links.\n\nRequires an array of relation IDs to delete. For example, if deleting relations with IDs [\"rel_123\", \"rel_456\", \"rel_789\"], all three connections will be permanently removed from the graph.\n\nCommon errors include providing non-existent relation IDs (operation will fail for invalid IDs but succeed for valid ones) and attempting to delete relations that don't exist. Always verify relation IDs exist using read_graph or search_nodes before deletion.\n\nUse delete_relations when removing multiple connections at once. For single relation removal, this tool still works efficiently. For removing entities entirely (which also removes their relations), use delete_entities instead. For removing specific observations while keeping relations intact, use delete_observations.\n\nNote: Deletion is permanent and cannot be undone. Relations connect entities in the knowledge graph, so removing them will break those specific connections while leaving the entities themselves intact."
+  },
+  {
+    "name": "read_graph",
+    "original": "Read the entire knowledge graph",
+    "rewritten": "Read and retrieve the complete knowledge graph structure including all entities, relationships, and observations. Use when the user wants to get a comprehensive overview of all stored knowledge, export the entire graph, or understand the full scope of available information before making queries or modifications.\n\nThis tool returns the entire graph dataset, making it ideal for initial exploration, data analysis, or when users ask broad questions like \"what do you know about?\" or \"show me everything.\" Unlike search_nodes (which finds specific matches) or open_nodes (which retrieves detailed node information), this provides the complete graph structure at once.\n\nNo parameters required - simply call to get all graph data. Handle large datasets carefully as this returns everything stored. If the graph is extensive, consider suggesting search_nodes for targeted queries instead. Common use cases include graph visualization preparation, full data exports, or comprehensive knowledge reviews.\n\nNote: For focused information retrieval, use search_nodes to find specific entities or open_nodes to get detailed node data rather than reading the entire graph."
+  },
+  {
+    "name": "search_nodes",
+    "original": "Search for nodes in the knowledge graph based on a query",
+    "rewritten": "Query the knowledge graph to find nodes matching specific search criteria. Use when the user wants to locate existing entities, find nodes by name or properties, or explore what's already stored in the graph before creating new content.\n\nProvide search terms that match node names, types, or attributes. For example: search for \"John Smith\" to find person entities, \"meeting\" to locate event nodes, or \"project alpha\" to find specific project entities. The search is typically case-insensitive and supports partial matching.\n\nCommon errors occur when searching too broadly (returns too many results) or too narrowly (returns nothing). Start with specific terms and broaden if needed. If no results appear, try alternative spellings or related terms.\n\nUse search_nodes BEFORE create_entities to avoid duplicates - always check if an entity already exists. Use read_graph when you need the complete graph structure, and open_nodes when you need to examine specific nodes you already know exist. This tool is for discovery and exploration of unknown content in the knowledge graph."
+  },
+  {
+    "name": "open_nodes",
+    "original": "Open specific nodes in the knowledge graph by their names",
+    "rewritten": "Open specific nodes in the knowledge graph by retrieving their detailed information using node names. Use when the user wants to examine particular entities they know by name, get comprehensive details about specific concepts, or drill down into individual nodes after discovering them through search.\n\nProvide exact node names as they appear in the graph - names are case-sensitive and must match precisely. For example, use \"Apple Inc.\" not \"apple inc\" or \"Apple\". Multiple nodes can be opened simultaneously by providing a list of names.\n\nCommon errors include misspelled names or using partial matches - if a node isn't found, try searching first with search_nodes to find the correct name format. Unlike search_nodes which finds nodes by partial text matching, open_nodes requires exact name matches and returns complete node data including all properties and relationships.\n\nUse this tool when you have specific node names and need their full details, versus search_nodes for discovery, read_graph for overall structure, or create_entities for adding new nodes."
+  }
+]