agent-capmap 0.1.0__tar.gz

agent_capmap-0.1.0/.env.example

@@ -0,0 +1,9 @@
+# Copy to .env (git-ignored) or export these in your shell. Never commit real values.
+
+# Required only for `--classify` without `--offline`.
+ANTHROPIC_API_KEY=<YOUR_API_KEY>
+
+# Optional overrides.
+# AGENTCAPMAP_MODEL=claude-opus-5-5
+# AGENTCAPMAP_EFFORT=medium
+# AGENTCAPMAP_CACHE_DIR=<PATH_TO_CACHE_DIR>

agent_capmap-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

agent_capmap-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,52 @@
+name: Bug report
+description: agent-capmap crashed, misread a config, or produced wrong output.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Before pasting anything, remove secrets.** agent-capmap redacts secrets in its own
+        output, but raw config files (`mcp.json`, `~/.claude.json`, `settings.json`) contain
+        API keys and tokens. Replace them with `<REDACTED>`. Security vulnerabilities go to
+        [private reporting](https://github.com/NKwolv/agent-capmap/security/advisories/new),
+        not here.
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `agentcapmap --version`.
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: OS and Python version
+      placeholder: Windows 11, Python 3.12
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command you ran
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: What happened
+      description: Error message or the relevant part of the output (secrets removed).
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: config
+    attributes:
+      label: Minimal config that reproduces it (optional, secrets removed)
+      render: json

agent_capmap-0.1.0/.github/ISSUE_TEMPLATE/classification.yml

@@ -0,0 +1,52 @@
+name: Wrong classification or finding
+description: A tool got the wrong capability tags, or a rule fired (or failed to fire) wrongly.
+labels: [classification]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        These reports improve the taxonomy, the classifier prompt and the evaluation set.
+        Tool definitions from public MCP servers are fine to paste; **remove secrets** and
+        anything internal from private servers. See
+        [docs/taxonomy.md](https://github.com/NKwolv/agent-capmap/blob/main/docs/taxonomy.md)
+        for what each tag means.
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind of problem
+      options:
+        - Wrong tag on a tool
+        - False positive (a finding that should not fire)
+        - False negative (a risk that was missed)
+        - Suspicious-description flag wrong
+    validations:
+      required: true
+  - type: input
+    id: server
+    attributes:
+      label: MCP server and version
+      placeholder: "@modelcontextprotocol/server-filesystem 2026.1.14"
+    validations:
+      required: true
+  - type: textarea
+    id: tool
+    attributes:
+      label: Tool definition
+      description: The tool's name, description and input schema, as returned by tools/list.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: got
+    attributes:
+      label: What agent-capmap reported
+      description: The tags (with evidence) or the finding, and the model used if you classified with an LLM.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected, and why
+    validations:
+      required: true

agent_capmap-0.1.0/.github/ISSUE_TEMPLATE/client_support.yml

@@ -0,0 +1,34 @@
+name: Support another AI client or config format
+description: Ask agent-capmap to read the MCP configuration of a client it does not support yet.
+labels: [enhancement, discovery]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Supported today: Claude Desktop, Cursor, VS Code, Claude Code and generic `mcp.json`.
+        Adding a client is a good first contribution; see "Adding a client config format" in
+        [CONTRIBUTING.md](https://github.com/NKwolv/agent-capmap/blob/main/CONTRIBUTING.md).
+  - type: input
+    id: client
+    attributes:
+      label: Client name and version
+      placeholder: Windsurf 1.12
+    validations:
+      required: true
+  - type: textarea
+    id: locations
+    attributes:
+      label: Where it stores MCP configuration
+      description: File paths per OS, and a link to the client's documentation if there is one.
+    validations:
+      required: true
+  - type: textarea
+    id: example
+    attributes:
+      label: Example config (secrets removed)
+      render: json
+  - type: textarea
+    id: approvals
+    attributes:
+      label: Approval / auto-approve settings (optional)
+      description: Does the client record which tools run without asking? Where?

agent_capmap-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/NKwolv/agent-capmap/security/advisories/new
+    about: Please report vulnerabilities privately, never in a public issue. See SECURITY.md.
+  - name: Ask a question
+    url: https://github.com/NKwolv/agent-capmap#readme
+    about: Check the README and docs/ first; if they do not answer it, open a bug report.

agent_capmap-0.1.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  # pyproject.toml ranges and the hash-pinned lockfiles in requirements/.
+  - package-ecosystem: pip
+    directories: ["/", "/requirements"]
+    schedule:
+      interval: weekly
+    # Let new releases age before proposing them (supply-chain safety).
+    cooldown:
+      default-days: 14
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 14
+    groups:
+      github-actions:
+        patterns: ["*"]

agent_capmap-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## What and why
+
+<!-- What does this change, and why is it needed? Link the issue if there is one. -->
+
+## Checklist
+
+- [ ] All checks from [CONTRIBUTING.md](../CONTRIBUTING.md) pass locally (ruff, mypy,
+      pytest, bandit, pip-audit, zizmor, gitleaks).
+- [ ] Tests added or updated, including negative cases for anything security-relevant.
+- [ ] No secrets, personal paths or real credentials in code, fixtures or output.
+- [ ] Untrusted input (configs, server responses, LLM output) is size-bounded and
+      validated; nothing from it reaches a shell, `eval` or a file path unchecked.
+- [ ] New dependencies are justified, verified on PyPI and added to the lockfiles.
+- [ ] Docs and CHANGELOG updated if behavior changed.
+
+## Security notes
+
+<!-- Trust boundaries touched, assumptions made, anything that needs a maintainer
+decision. Write "None" if the change has no security impact. -->

agent_capmap-0.1.0/.github/workflows/action-selftest.yml

@@ -0,0 +1,69 @@
+name: Action self-test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Read-only: the self-test runs the local action and checks its outputs; it uploads
+# nothing (code scanning upload is exercised by users' workflows, see docs/examples).
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  selftest:
+    name: Run the action on the scenario fixtures
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - id: capmap
+        # The self-test must run the action from this checkout (the commit under test).
+        # The $/ self-repository form is not documented for a root-level action.yml.
+        uses: ./ # zizmor: ignore[self-repository]
+        with:
+          path: fixtures
+          fail-on: none
+          sarif-file: selftest.sarif
+      - name: Check outputs and SARIF
+        shell: bash
+        env:
+          FINDINGS: ${{ steps.capmap.outputs.findings }}
+          SARIF: ${{ steps.capmap.outputs.sarif-file }}
+        run: |
+          set -euo pipefail
+          # Without enumeration only config-level rules can fire: CAP-007 on the
+          # unpinned server in fixtures/overscoped-token.
+          test "$FINDINGS" = "1"
+          python - "$SARIF" <<'EOF'
+          import json, sys
+          sarif = json.load(open(sys.argv[1], encoding="utf-8"))
+          assert sarif["version"] == "2.1.0"
+          (result,) = sarif["runs"][0]["results"]
+          assert result["ruleId"] == "CAP-007", result["ruleId"]
+          uri = result["locations"][0]["physicalLocation"]["artifactLocation"]["uri"]
+          assert uri == "fixtures/overscoped-token/mcp.json", uri
+          print("SARIF ok:", result["ruleId"], uri)
+          EOF
+      - name: Gate fails at medium
+        id: gate
+        continue-on-error: true
+        uses: ./ # zizmor: ignore[self-repository]
+        with:
+          path: fixtures
+          fail-on: medium
+          sarif-file: gate.sarif
+      - name: Check the gate failed
+        shell: bash
+        env:
+          OUTCOME: ${{ steps.gate.outcome }}
+        run: test "$OUTCOME" = "failure"

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

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Read-only token: CI only checks out code and runs local tools.
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      # Actions are pinned to full commit SHAs; Dependabot keeps them current.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (hash-pinned lockfile, no unpinned build dependencies)
+        run: |
+          python -m pip install --require-hashes -r requirements/dev.lock
+          python -m pip install --no-deps --no-build-isolation -e .
+      - name: Ruff (lint, incl. security rules)
+        run: ruff check . && ruff format --check .
+      - name: Mypy
+        run: mypy
+      - name: Pytest
+        run: pytest
+
+  security:
+    name: Security scans (SAST + SCA)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --require-hashes -r requirements/dev.lock
+          python -m pip install --no-deps --no-build-isolation -e .
+      - name: SAST (bandit)
+        run: bandit -c pyproject.toml -r src
+      - name: SCA (pip-audit on every locked dependency)
+        run: pip-audit --strict --require-hashes -r requirements/dev.lock
+      - name: Workflow security (zizmor)
+        run: zizmor --offline --persona auditor action.yml .github/workflows/
+
+  secrets:
+    name: Secret scanning (gitleaks, full history)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: gitleaks
+        # Official image pinned by digest (v8.30.1), no network. Runs as the runner user
+        # so git's ownership check passes; --redact keeps any finding out of the log.
+        run: >
+          docker run --rm --network none --user "$(id -u):$(id -g)"
+          -v "${GITHUB_WORKSPACE}:/repo"
+          ghcr.io/gitleaks/gitleaks@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f
+          git /repo --config /repo/.gitleaks.toml --redact --no-banner --exit-code 1
+
+  sbom:
+    name: SBOM (CycloneDX)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Install tooling
+        run: python -m pip install --require-hashes -r requirements/dev.lock
+      - name: Build wheel and a clean runtime environment
+        # The SBOM describes exactly what a user installs: the runtime lockfile plus
+        # this package, in an environment with no installer tooling.
+        run: |
+          python -m pip wheel --no-deps --no-build-isolation -w dist .
+          python -m venv --without-pip runtime-env
+          python -m pip --python runtime-env/bin/python install --require-hashes -r requirements/runtime.lock
+          python -m pip --python runtime-env/bin/python install --no-deps --no-index dist/*.whl
+      - name: Generate SBOM
+        run: >
+          cyclonedx-py environment --pyproject pyproject.toml --mc-type application
+          --output-format JSON --output-reproducible -o sbom.cdx.json runtime-env/bin/python
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: sbom
+          path: sbom.cdx.json
+          if-no-files-found: error

agent_capmap-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,40 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 3 * * 1"
+
+# Default to read-only; the analyze job widens only what CodeQL needs.
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: CodeQL (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # check out the code
+      security-events: write # upload CodeQL results to code scanning
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python, actions]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-and-quality
+      - uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        with:
+          category: /language:${{ matrix.language }}

agent_capmap-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,109 @@
+name: Release
+
+# Publishes a version to PyPI and GitHub Releases when a tag like v0.1.0 is pushed.
+# PyPI uses trusted publishing (OIDC): no API token is stored in this repository.
+on:
+  push:
+    tags: ["v*"]
+
+# Every job declares the minimum it needs.
+permissions: {}
+
+# One release at a time, and never cancel one halfway through publishing.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify (tests and SCA)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Check the tag matches the package version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "$TAG" != "v$version" ]; then
+            echo "::error::Tag $TAG does not match version $version in pyproject.toml"
+            exit 1
+          fi
+      - name: Install (hash-pinned lockfile)
+        run: |
+          python -m pip install --require-hashes -r requirements/dev.lock
+          python -m pip install --no-deps --no-build-isolation -e .
+      - name: Tests
+        run: pytest
+      - name: SCA (pip-audit on every locked dependency)
+        run: |
+          pip-audit --strict --require-hashes -r requirements/runtime.lock
+          pip-audit --strict --require-hashes -r requirements/build.lock
+
+  build:
+    name: Build distributions
+    needs: verify
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel (hash-pinned build backend)
+        run: |
+          python -m pip install --require-hashes -r requirements/build.lock
+          python -m hatchling build -t sdist -t wheel
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Configure this environment on GitHub with a required reviewer so every release
+    # needs a manual approval; PyPI's trusted publisher is bound to it.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agent-capmap/
+    permissions:
+      id-token: write # OIDC token for trusted publishing and attestations
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  github-release:
+    name: GitHub release
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the release and upload the distributions
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: >
+          gh release create "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --verify-tag
+          --title "$TAG"
+          --notes "See [CHANGELOG.md](https://github.com/$GITHUB_REPOSITORY/blob/$TAG/CHANGELOG.md). Install: \`pipx install agent-capmap==${TAG#v}\`"

agent_capmap-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Secrets and credentials: never commit (AGENTS.md section 1)
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+credentials*
+*.tfstate
+*.tfstate.*
+kubeconfig
+.secrets/
+
+# Local classifier cache and scan output (may contain tool descriptions)
+.agentcapmap/
+/inventory*.json
+/sbom*.json

agent_capmap-0.1.0/.gitleaks.toml

@@ -0,0 +1,15 @@
+title = "agent-capmap secret scanning"
+
+# Start from gitleaks' maintained default rule set.
+[extend]
+useDefault = true
+
+# Test fixtures deliberately contain credential-shaped values so redaction can be
+# tested, and every one of them contains "fake" (see tests/fake_secrets.py).
+#
+# This allowlist matches on the secret value only. Do NOT add `paths` here: in gitleaks
+# 8.30 a path entry skips matching files entirely, even with condition = "AND", which
+# would hide a real secret placed in tests/ (verified by a negative test).
+[[allowlists]]
+description = "Deliberately fake credentials (value contains 'fake')"
+regexes = ['''(?i)fake''']

agent_capmap-0.1.0/.gitleaksignore

@@ -0,0 +1,7 @@
+# Exact gitleaks findings reviewed and accepted. Each entry is one finding in one commit;
+# anything new is still reported.
+#
+# Phase 1 commit: deliberately fake test values that did not yet contain "fake".
+# Since replaced (tests/fake_secrets.py PATH_SECRET, tests/test_redact.py JWT sample).
+bc368719f073b650f42dd721394bfa5db74c4f75:tests/test_redact.py:jwt:39
+bc368719f073b650f42dd721394bfa5db74c4f75:tests/fake_secrets.py:generic-api-key:13

agent_capmap-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# All hooks run the tool versions pinned in requirements/dev.lock (installed in your
+# venv), so pre-commit never fetches unpinned third-party hook code.
+repos:
+  - repo: local
+    hooks:
+      - id: ruff
+        name: ruff (lint, incl. security rules)
+        entry: ruff check --fix
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: ruff format
+        entry: ruff format
+        language: system
+        types: [python]
+      - id: mypy
+        name: mypy
+        entry: mypy
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: bandit
+        name: bandit (SAST)
+        entry: bandit -q -c pyproject.toml -r src
+        language: system
+        types: [python]
+        pass_filenames: false