armature-mcp-analytics 0.1.0__tar.gz

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

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: Checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run checks
+        run: PYTHONPATH=src python -m unittest discover -s tests
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+

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

@@ -0,0 +1,140 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: publish-pypi
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    if: github.repository == 'armature-tech/mcp-analytics-python'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check whether this commit is already released
+        id: existing_release
+        run: |
+          set -euo pipefail
+          tag="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1 || true)"
+          if [[ -n "${tag}" ]]; then
+            echo "Commit ${GITHUB_SHA} already has release tag ${tag}; skipping publish."
+            echo "published=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "published=false" >> "${GITHUB_OUTPUT}"
+          fi
+
+      - name: Setup Python
+        if: steps.existing_release.outputs.published != 'true'
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run checks
+        if: steps.existing_release.outputs.published != 'true'
+        run: PYTHONPATH=src python -m unittest discover -s tests
+
+      - name: Resolve next patch version
+        if: steps.existing_release.outputs.published != 'true'
+        id: version
+        env:
+          INITIAL_VERSION: "0.1.0"
+        run: |
+          set -euo pipefail
+          python <<'PY'
+          import json
+          import os
+          import re
+          import subprocess
+          import sys
+          import urllib.error
+          import urllib.request
+          from pathlib import Path
+
+          pyproject_path = Path("pyproject.toml")
+          text = pyproject_path.read_text()
+          name_match = re.search(r'^name = "([^"]+)"$', text, re.MULTILINE)
+          if not name_match:
+              raise SystemExit("Could not find project name in pyproject.toml")
+          package_name = name_match.group(1)
+
+          versions = []
+
+          def add_version(candidate):
+              if not isinstance(candidate, str):
+                  return
+              normalized = candidate.strip().removeprefix("v")
+              if re.fullmatch(r"\d+\.\d+\.\d+", normalized):
+                  versions.append(normalized)
+
+          try:
+              with urllib.request.urlopen(f"https://pypi.org/pypi/{package_name}/json", timeout=15) as response:
+                  data = json.load(response)
+              for version in data.get("releases", {}):
+                  add_version(version)
+          except urllib.error.HTTPError as error:
+              if error.code != 404:
+                  print(f"Could not read PyPI versions for {package_name}: HTTP {error.code}", file=sys.stderr)
+          except Exception as error:
+              print(f"Could not read PyPI versions for {package_name}: {error}", file=sys.stderr)
+
+          try:
+              subprocess.run(["git", "fetch", "--tags", "--force"], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+              tags = subprocess.check_output(["git", "tag", "-l", "v*"], text=True)
+              for tag in tags.splitlines():
+                  add_version(tag)
+          except Exception as error:
+              print(f"Could not read git tags: {error}", file=sys.stderr)
+
+          if versions:
+              def parsed(version):
+                  return tuple(int(part) for part in version.split("."))
+              major, minor, patch = max(parsed(version) for version in versions)
+              next_version = f"{major}.{minor}.{patch + 1}"
+          else:
+              next_version = os.environ["INITIAL_VERSION"]
+
+          text = re.sub(r'^version = "[^"]+"$', f'version = "{next_version}"', text, count=1, flags=re.MULTILINE)
+          pyproject_path.write_text(text)
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output:
+              output.write(f"next_version={next_version}\n")
+          print(f"Publishing {package_name}=={next_version}")
+          PY
+
+      - name: Build distributions
+        if: steps.existing_release.outputs.published != 'true'
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+          python -m tarfile -l dist/*.tar.gz
+          python -m zipfile -l dist/*.whl
+
+      - name: Publish
+        if: steps.existing_release.outputs.published != 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub release
+        if: steps.existing_release.outputs.published != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NEXT_VERSION: ${{ steps.version.outputs.next_version }}
+        run: |
+          set -euo pipefail
+          gh release create "v${NEXT_VERSION}" \
+            --target "${GITHUB_SHA}" \
+            --title "v${NEXT_VERSION}" \
+            --notes "Published armature-mcp-analytics==${NEXT_VERSION} from ${GITHUB_SHA}."

armature_mcp_analytics-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: armature-mcp-analytics
+Version: 0.1.0
+Summary: Armature analytics wrapper SDK for Python MCP servers.
+Project-URL: Homepage, https://armature.tech
+Project-URL: Repository, https://github.com/armature-tech/mcp-analytics-python
+Author-email: Armature <support@armature.tech>
+License-Expression: Apache-2.0
+Keywords: analytics,armature,fastmcp,mcp,model-context-protocol,observability,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp<4,>=2; extra == 'fastmcp'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# armature-mcp-analytics
+
+Armature analytics for Python MCP servers. The v1 integration is FastMCP-first:
+instrument a `FastMCP` instance, keep writing normal tools, and Armature records
+tool calls with MCP-specific telemetry.
+
+Install:
+
+```bash
+pip install "armature-mcp-analytics[fastmcp]"
+```
+
+```python
+import os
+from fastmcp import FastMCP
+from armature_mcp_analytics import instrument_fastmcp
+
+mcp = FastMCP("Customer MCP")
+
+instrument_fastmcp(
+    mcp,
+    {
+        "armature": {
+            "api_key": os.getenv("ANALYTICS_INGEST_API_KEY"),
+            "delivery": "await",
+        }
+    },
+)
+
+@mcp.tool
+def lookup_customer(customer_id: str) -> dict:
+    """Look up a customer by id."""
+    return {"customer_id": customer_id, "status": "active"}
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+Agents see an optional `telemetry` object on each tool input schema. The SDK
+strips that object before your handler runs, then emits an authenticated batch
+to Armature.
+
+Environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `ANALYTICS_INGEST_API_KEY` | Armature ingest API key. Missing keys no-op for local development. |
+| `ANALYTICS_INGEST_URL` | Optional ingest endpoint override. |

armature_mcp_analytics-0.1.0/README.md

@@ -0,0 +1,48 @@
+# armature-mcp-analytics
+
+Armature analytics for Python MCP servers. The v1 integration is FastMCP-first:
+instrument a `FastMCP` instance, keep writing normal tools, and Armature records
+tool calls with MCP-specific telemetry.
+
+Install:
+
+```bash
+pip install "armature-mcp-analytics[fastmcp]"
+```
+
+```python
+import os
+from fastmcp import FastMCP
+from armature_mcp_analytics import instrument_fastmcp
+
+mcp = FastMCP("Customer MCP")
+
+instrument_fastmcp(
+    mcp,
+    {
+        "armature": {
+            "api_key": os.getenv("ANALYTICS_INGEST_API_KEY"),
+            "delivery": "await",
+        }
+    },
+)
+
+@mcp.tool
+def lookup_customer(customer_id: str) -> dict:
+    """Look up a customer by id."""
+    return {"customer_id": customer_id, "status": "active"}
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+Agents see an optional `telemetry` object on each tool input schema. The SDK
+strips that object before your handler runs, then emits an authenticated batch
+to Armature.
+
+Environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `ANALYTICS_INGEST_API_KEY` | Armature ingest API key. Missing keys no-op for local development. |
+| `ANALYTICS_INGEST_URL` | Optional ingest endpoint override. |

armature_mcp_analytics-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "armature-mcp-analytics"
+version = "0.1.0"
+description = "Armature analytics wrapper SDK for Python MCP servers."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+  { name = "Armature", email = "support@armature.tech" },
+]
+keywords = [
+  "mcp",
+  "model-context-protocol",
+  "analytics",
+  "telemetry",
+  "observability",
+  "armature",
+  "fastmcp",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+fastmcp = [
+  "fastmcp>=2,<4",
+]
+mcp = [
+  "mcp>=1.27,<2",
+]
+
+[project.urls]
+Homepage = "https://armature.tech"
+Repository = "https://github.com/armature-tech/mcp-analytics-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/armature_mcp_analytics"]

armature_mcp_analytics-0.1.0/src/armature_mcp_analytics/__init__.py

@@ -0,0 +1,47 @@
+"""Armature analytics helpers for Python MCP servers."""
+
+from .events import (
+    build_actor_id,
+    build_event_id,
+    build_session_init_event,
+    build_tool_call_event,
+    normalize_session_id,
+)
+from .recorder import AnalyticsRecorder, create_analytics_recorder
+from .schema import (
+    append_telemetry_hint,
+    create_telemetry_json_schema,
+    decorate_input_schema_with_telemetry,
+    extract_telemetry_arguments,
+)
+from .server import FastMCPInstrumentation, instrument_fastmcp, with_mcp_analytics
+from .types import (
+    AnalyticsConfig,
+    AnalyticsIngestBatch,
+    AnalyticsIngestEvent,
+    McpClientInfo,
+    TelemetryArgs,
+)
+
+__all__ = [
+    "AnalyticsConfig",
+    "AnalyticsIngestBatch",
+    "AnalyticsIngestEvent",
+    "AnalyticsRecorder",
+    "FastMCPInstrumentation",
+    "McpClientInfo",
+    "TelemetryArgs",
+    "append_telemetry_hint",
+    "build_actor_id",
+    "build_event_id",
+    "build_session_init_event",
+    "build_tool_call_event",
+    "create_analytics_recorder",
+    "create_telemetry_json_schema",
+    "decorate_input_schema_with_telemetry",
+    "extract_telemetry_arguments",
+    "instrument_fastmcp",
+    "normalize_session_id",
+    "with_mcp_analytics",
+]
+

armature_mcp_analytics-0.1.0/src/armature_mcp_analytics/emit.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .types import ActorIdResolverInput, AnalyticsConfig, AnalyticsIngestBatch
+from .utils import header_value, read_env
+
+DEFAULT_ENDPOINT_URL = "https://app.armature.tech/api/mcp-analytics/ingest"
+DEFAULT_TIMEOUT_MS = 500
+
+
+def _armature(config: AnalyticsConfig | None) -> dict[str, Any]:
+    return dict((config or {}).get("armature") or {})
+
+
+def _config_value(config: AnalyticsConfig | None, snake: str, camel: str, default: Any = None) -> Any:
+    armature = _armature(config)
+    if snake in armature:
+        return armature[snake]
+    if camel in armature:
+        return armature[camel]
+    return default
+
+
+def resolve_endpoint_url(config: AnalyticsConfig | None = None) -> str:
+    return (
+        _config_value(config, "endpoint_url", "endpointUrl")
+        or read_env("ANALYTICS_INGEST_URL")
+        or DEFAULT_ENDPOINT_URL
+    )
+
+
+def resolve_api_key(config: AnalyticsConfig | None = None) -> str | None:
+    return _config_value(config, "api_key", "apiKey") or read_env("ANALYTICS_INGEST_API_KEY")
+
+
+async def resolve_actor_seed(config: AnalyticsConfig | None, input: ActorIdResolverInput) -> str:
+    actor_id = _config_value(config, "actor_id", "actorId")
+    if callable(actor_id):
+        value = actor_id(input)
+        if asyncio.iscoroutine(value) or isinstance(value, asyncio.Future):
+            value = await value
+        return str(value)
+    if actor_id:
+        return str(actor_id)
+
+    auth_info = input.get("authInfo") or {}
+    for key in ("token", "clientId", "apiKey", "principalId"):
+        value = auth_info.get(key)
+        if value:
+            return str(value)
+
+    authorization = header_value(input.get("headers"), "authorization")
+    if authorization:
+        return authorization
+    return "anonymous"
+
+
+async def post_telemetry_event(
+    batch: AnalyticsIngestBatch,
+    config: AnalyticsConfig | None = None,
+) -> dict[str, Any]:
+    api_key = resolve_api_key(config)
+    if not api_key:
+        return {"skipped": True, "reason": "ingest_config_missing"}
+
+    body = json.dumps(batch, separators=(",", ":")).encode("utf-8")
+    request = urllib.request.Request(
+        resolve_endpoint_url(config),
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+        method="POST",
+    )
+    timeout_ms = _config_value(config, "timeout_ms", "timeoutMs", DEFAULT_TIMEOUT_MS)
+    timeout = float(timeout_ms) / 1000
+
+    def send() -> dict[str, Any]:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            status = response.getcode()
+            return {"skipped": False, "ok": True, "status": status}
+
+    try:
+        return await asyncio.to_thread(send)
+    except urllib.error.HTTPError as error:
+        detail = error.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Armature ingest failed with {error.code}: {detail}") from error
+
+
+class FlushableEmitter:
+    def __init__(self, config: AnalyticsConfig | None = None) -> None:
+        self.config = config or {}
+        self._pending: set[asyncio.Task[None]] = set()
+
+    def _enabled(self) -> bool:
+        return _config_value(self.config, "enabled", "enabled", True) is not False
+
+    def _delivery(self) -> str:
+        return str(_config_value(self.config, "delivery", "delivery", "background"))
+
+    def _emit_callable(self):
+        return _config_value(self.config, "emit", "emit")
+
+    def _on_error(self):
+        return _config_value(self.config, "on_error", "onError")
+
+    async def _run(self, batch: AnalyticsIngestBatch) -> None:
+        try:
+            emit = self._emit_callable()
+            if emit:
+                result = emit(batch)
+                if asyncio.iscoroutine(result) or isinstance(result, asyncio.Future):
+                    await result
+            else:
+                await post_telemetry_event(batch, self.config)
+        except Exception as error:
+            # Telemetry delivery should not crash the host MCP server. Await
+            # mode waits for the attempt to finish; failures are surfaced only
+            # through the optional error hook, matching the JS SDK contract.
+            on_error = self._on_error()
+            if on_error:
+                try:
+                    result = on_error(error, batch)
+                    if asyncio.iscoroutine(result) or isinstance(result, asyncio.Future):
+                        await result
+                except Exception:
+                    pass
+
+    async def emit_batch(self, batch: AnalyticsIngestBatch) -> None:
+        if not self._enabled():
+            return
+        if self._delivery() == "await":
+            await self._run(batch)
+            return
+        loop = asyncio.get_running_loop()
+        task = loop.create_task(self._run(batch))
+        self._pending.add(task)
+        task.add_done_callback(lambda done: self._pending.discard(done))
+
+    async def flush(self) -> None:
+        while self._pending:
+            await asyncio.gather(*list(self._pending), return_exceptions=True)
+
+
+def create_flushable_emitter(config: AnalyticsConfig | None = None) -> FlushableEmitter:
+    return FlushableEmitter(config)