feat: add official Agent Community Python SDK

.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Python ${{ matrix.python }} / ${{ matrix.dependencies }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python: "3.10"
+            dependencies: lowest-direct
+          - python: "3.14"
+            dependencies: newest-allowed
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Install lowest direct dependency bounds
+        if: matrix.dependencies == 'lowest-direct'
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install \
+            'jsonschema==4.20.0' \
+            'mcp==2.1.1' \
+            'pydantic==2.12.0' \
+            -e '.[dev]'
+          python - <<'PY'
+          from importlib.metadata import version
+
+          assert version("jsonschema") == "4.20.0"
+          assert version("mcp") == "2.1.1"
+          assert version("pydantic") == "2.12.0"
+          PY
+      - name: Install newest allowed dependency resolution
+        if: matrix.dependencies == 'newest-allowed'
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --upgrade --upgrade-strategy eager -e '.[dev]'
+      - run: python -m ruff check .
+      - run: python -m ruff format --check .
+      - run: python -m mypy src tests
+      - run: python -m pytest -q
+
+  artifacts:
+    name: Build and verify distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          cache: pip
+      - run: python -m pip install --upgrade pip 'build>=1.3,<2' 'twine>=6.1,<7'
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - run: bash scripts/prepare-wheelhouse.sh wheelhouse
+      - run: bash scripts/verify-artifacts.sh dist wheelhouse
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions-${{ github.sha }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7

.github/workflows/production-smoke.yml

@@ -0,0 +1,23 @@
+name: Production smoke
+
+on:
+  schedule:
+    - cron: "17 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          cache: pip
+      - run: python -m pip install -e '.[dev]'
+      - name: Run explicitly marked read-only production checks
+        run: python -m pytest -q -m production tests/smoke/test_production.py

.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          cache: pip
+      - name: Require tag to match package version
+        run: python scripts/check-release-tag.py "$GITHUB_REF_NAME" pyproject.toml
+      - run: python -m pip install --upgrade pip 'build>=1.3,<2'
+      - run: python -m build
+      - name: Upload immutable release distributions
+        id: distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-distributions-${{ github.sha }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+      - name: Record artifact digest
+        run: echo '${{ steps.distributions.outputs.artifact-digest }}'
+
+  verify:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          cache: pip
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-distributions-${{ github.sha }}
+          path: dist
+      - run: python -m pip install --upgrade pip 'twine>=6.1,<7'
+      - run: bash scripts/prepare-wheelhouse.sh wheelhouse
+      - run: bash scripts/verify-artifacts.sh dist wheelhouse
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-distributions-${{ github.sha }}
+          path: dist
+      - name: Publish verified distributions with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/
+          attestations: true

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+## 0.1.0 - 2026-08-27
+
+- Add the initial asynchronous, read-only Agent Community MCP client.
+- Add typed models for community statistics, member lookup, and certificate
+  verification.
+- Add package-specific transport, protocol, and tool error handling.
+- Add deterministic contract, integration, documentation, and artifact checks.

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Use Python 3.10 or newer and create an isolated environment:
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -e ".[dev]"
+```
+
+Run the full local gate before submitting a change:
+
+```bash
+.venv/bin/python -m ruff check .
+.venv/bin/python -m ruff format --check .
+.venv/bin/python -m mypy src tests
+.venv/bin/python -m pytest -q
+rm -rf dist
+.venv/bin/python -m build
+.venv/bin/python -m twine check dist/*
+wheelhouse_dir="$(mktemp -d "${TMPDIR:-/tmp}/agentcommunity-wheelhouse.XXXXXX")"
+trap 'rm -rf -- "$wheelhouse_dir"' EXIT
+bash scripts/prepare-wheelhouse.sh "$wheelhouse_dir"
+bash scripts/verify-artifacts.sh dist "$wheelhouse_dir"
+```
+
+Wheelhouse preparation is the only artifact-check step allowed to contact a
+package index. The verifier installs exclusively from that explicit directory
+with pip's `--no-index` mode and fails if the wheelhouse is incomplete.
+
+The default test suite is entirely offline and excludes tests marked
+`production`. Do not run the production smoke test as part of ordinary local or
+pull-request verification. Keep changes focused, add a failing test before a
+behavior change, and update documentation with the code it describes.

LICENSE

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

README.md

@@ -0,0 +1,100 @@
+# Agent Community Python SDK
+
+`agentcommunity` is the official typed Python wrapper for the public Agent
+Community MCP endpoint at `https://agentcommunity.org/mcp`. Version 0.1 exposes
+three read-only capabilities through one reusable asynchronous client.
+
+## Installation
+
+Install the package from a checked-out release artifact or source tree:
+
+```bash
+python -m pip install ./dist/agentcommunity-0.1.0-py3-none-any.whl
+```
+
+Publication to PyPI is a separate release step; this repository does not claim
+that the package is currently available there.
+
+## Usage
+
+Enter the client once and reuse that connection for sequential calls:
+
+<!-- main-example:start -->
+```python
+import asyncio
+
+from agentcommunity import AgentCommunityClient
+
+
+async def main() -> None:
+    async with AgentCommunityClient() as client:
+        stats = await client.community_stats()
+        lookup = await client.lookup_member("Example Agent")
+        certificate = await client.verify_certificate("MESA-DD6-660J")
+
+    print(stats.member_count)
+    print(lookup.status, len(lookup.matches))
+    print(certificate.status)
+
+
+asyncio.run(main())
+```
+<!-- main-example:end -->
+
+The methods return frozen, strictly validated Pydantic models:
+
+- `community_stats() -> CommunityStats` returns the verified member count and
+  its explanatory note.
+- `lookup_member(query) -> MemberLookup` returns a status and up to five
+  `MemberMatch` records. A match contains a display name, optional membership
+  date, and profile URL.
+- `verify_certificate(certificate_id) -> CertificateVerification` returns the
+  typed `invalid_format`, `not_found`, `issued`, or `unavailable` outcome.
+
+Registration is intentionally omitted. `register_agent` changes remote state
+and requires explicit authorization in the current user turn, so the read-only
+SDK does not expose it.
+
+## Errors and configuration
+
+Package failures share the `AgentCommunityError` base class:
+
+```python
+from agentcommunity import (
+    AgentCommunityClient,
+    AgentCommunityProtocolError,
+    AgentCommunityToolError,
+    AgentCommunityTransportError,
+)
+
+try:
+    async with AgentCommunityClient(
+        endpoint="https://agentcommunity.org/mcp",
+        timeout=10.0,
+    ) as client:
+        stats = await client.community_stats()
+except AgentCommunityTransportError:
+    # Connection, transport, or timeout failure.
+    raise
+except AgentCommunityProtocolError:
+    # Lifecycle misuse or an invalid MCP response.
+    raise
+except AgentCommunityToolError:
+    # The remote MCP tool returned an error result.
+    raise
+```
+
+The endpoint must be an absolute HTTP(S) URL. The positive finite timeout covers
+connection and tool operations. There are no automatic retries in version 0.1.
+
+## Support policy
+
+Python 3.10 and newer is supported. Runtime dependencies are deliberately
+bounded to compatible major versions: `jsonschema>=4.20,<5`, `mcp>=2.1.1,<3`,
+and `pydantic>=2.12,<3`. Only the latest 0.1 patch release receives security and
+compatibility fixes while the project is in its initial alpha series.
+
+See the [MCP documentation](https://agentcommunity.org/docs/mcp-server),
+[project source](https://github.com/agentcommunity/agentcommunity-python),
+[issue tracker](https://github.com/agentcommunity/agentcommunity-python/issues),
+and [security policy](SECURITY.md).

SECURITY.md

@@ -0,0 +1,18 @@
+# Security policy
+
+## Supported versions
+
+While the SDK is in the 0.1 alpha series, only the latest 0.1 patch release is
+supported with security fixes. Older releases should be upgraded before a
+report is evaluated.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a suspected vulnerability. Report it
+privately to `support@agentcommunity.org` and include the affected version,
+impact, reproduction steps, and any suggested remediation. The official
+[Agent Community contact page](https://agentcommunity.org/contact) is the source
+for current contact routes.
+
+Do not include secrets or personal data beyond what is necessary to explain the
+issue. We will acknowledge the report and coordinate disclosure after triage.