Squashed commit from mcp/agentops-api changes

Author: the-praxs

Dockerfile

@@ -0,0 +1,36 @@
+# Use a Python image with uv pre-installed
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS uv
+
+# Install the project into `/app`
+WORKDIR /app
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Install the project's dependencies using the lockfile and settings
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev --no-editable
+
+# Then, add the rest of the project source code and install it
+# Installing separately from its dependencies allows optimal layer caching
+ADD . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-editable
+
+FROM python:3.12-slim-bookworm
+
+WORKDIR /app
+ 
+COPY --from=uv /root/.local /root/.local
+COPY --from=uv --chown=app:app /app/.venv /app/.venv
+
+# Place executables in the environment at the front of the path
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Use default API URL (https://api.agentops.ai) - agents can override per-request
+ENTRYPOINT ["python", "-m", "mcp_server_agentops_api"]

README.md

@@ -0,0 +1,142 @@
+# AgentOps API MCP Server
+
+An MCP (Model Coordination Protocol) server that allows LLM agents to interact with the AgentOps API for accessing trace data.
+
+## Overview
+
+This MCP server provides tools for agents to:
+
+- List recent traces from their AgentOps project
+- Get detailed information about specific traces
+
+The server handles authentication and communication with the AgentOps API, making it easy for agents to access their trace data.
+
+## Authentication Flow
+
+The server uses a secure two-step authentication process:
+
+1. The agent provides their AgentOps API key with each request
+2. The server exchanges this API key for a JWT token from the AgentOps API
+3. The server uses this JWT token to make authenticated requests to the AgentOps API
+4. All responses are passed back to the agent in their raw form
+
+This ensures that API keys are never stored between requests, and each request is authenticated securely with a JWT token.
+
+## Available Tools
+
+### `list_traces`
+
+Lists the most recent traces from the agent's project.
+
+**Parameters:**
+- `AGENTOPS_API_KEY` (required): The agent's AgentOps API key
+- `limit` (optional): Maximum number of traces to return (default: 5)
+- `AGENTOPS_API_URL` (optional): Custom API URL for non-production environments
+
+**Response:**
+- List of traces with trace ID, number of spans, start/end time
+- Total number of traces in the database
+- Traces sorted by creation timestamp (most recent first)
+
+### `trace_detail`
+
+Gets detailed information about a specific trace.
+
+**Parameters:**
+- `AGENTOPS_API_KEY` (required): The agent's AgentOps API key
+- `trace_id` (required): The trace ID to retrieve details for (from the `trace_id` field in `list_traces` response)
+- `AGENTOPS_API_URL` (optional): Custom API URL for non-production environments
+
+**Response:**
+- Detailed information about the trace
+- All spans associated with the trace
+- Metadata, timing information, etc.
+
+## Usage
+
+### Using with Claude Coder (Recommended)
+
+This MCP server is designed to work with Claude Coder. Follow these steps to set it up:
+
+1. **Configure Claude Coder**
+
+   Add this to your Claude Coder configuration file (typically `~/.config/claude-cli/config.yaml`):
+
+   ```yaml
+   mcp_servers:
+     - name: agentops-api
+       path: /ABSOLUTE/PATH/TO/mcp/agentops-api/bin/run-server
+       description: "AgentOps API integration for accessing trace data"
+   ```
+
+   Replace `/ABSOLUTE/PATH/TO` with the actual path to this repository.
+
+2. **Use with Claude Coder**
+
+   ```bash
+   # Run Claude with the AgentOps API MCP server enabled
+   claude --mcp agentops-api
+   
+   # Or for a single command
+   claude --mcp agentops-api "List my recent traces. My API key is xyz123"
+   ```
+
+3. **In your prompts to Claude, include your AgentOps API key:**
+
+   ```
+   Can you show me my recent traces? Find my agentops api key in my user .env file. 
+   ```
+
+### Running Standalone
+
+If you need to run the server directly:
+
+```bash
+# Using the convenience script
+./bin/run-server
+
+# Or using Python directly
+uv run -m mcp_server_agentops_api
+```
+
+The server uses the production AgentOps API at `https://api.agentops.ai` by default. Agents can override this URL on a per-request basis.
+
+### Available Tool Calls
+
+When using the MCP server through Claude, these are the tools it can use:
+
+```
+# List recent traces
+list_traces(AGENTOPS_API_KEY="your-api-key", limit=10)
+
+# Get details for a specific trace
+trace_detail(AGENTOPS_API_KEY="your-api-key", trace_id="148dac266d95c9dc0b5616320b8488c9")
+
+# Using a custom API URL (e.g., for local development)
+list_traces(AGENTOPS_API_KEY="your-api-key", AGENTOPS_API_URL="http://localhost:8000")
+```
+
+## Architecture
+
+The code is organized into three main components:
+
+1. **Client (`client.py`)**: Handles communication with the AgentOps API, including authentication
+2. **Tools (`tools.py`)**: Defines the tools available to agents and processes tool requests
+3. **Server (`server.py`)**: Implements the MCP server that agents interact with
+
+Each request is stateless, with no user data stored between requests, and raw API responses are returned directly to the agent.
+
+## Docker
+
+```bash
+# Build and run the Docker container
+docker build -t mcp-server-agentops-api .
+docker run mcp-server-agentops-api
+```
+
+## Future Enhancements
+
+- Additional AgentOps API tools (metrics, spans, etc.)
+- Support for filtering and searching traces
+- Batch operations for improved performance
+- Caching of JWT tokens for a short period

bin/run-server

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+# Get the absolute path to the script directory
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+# Go to the parent directory (project root)
+cd "$SCRIPT_DIR/.."
+
+# Run the MCP server
+uv run -m mcp_server_agentops_api "$@"

pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "mcp-server-agentops-api"
+version = "0.1.0"
+description = "A Model Context Protocol server for the AgentOps API"
+readme = "README.md"
+requires-python = ">= 3.10"
+authors = [{ name = "AgentOps" }]
+keywords = ["agentops", "analytics", "mcp", "llm", "monitoring"]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+]
+dependencies = [
+    "httpx >= 0.25.0",
+    "mcp >= 1.1.3",
+    "pydantic >= 2.0.0",
+]
+
+[project.scripts]
+mcp-server-agentops-api = "mcp_server_agentops_api:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = ["pyright >= 1.1.389", "ruff >= 0.7.3"]

src/mcp_server_agentops_api/__init__.py

@@ -0,0 +1,24 @@
+from .server import serve
+
+# Default API endpoint
+DEFAULT_API_URL = "https://api.agentops.ai"
+
+def main():
+    """MCP AgentOps API Server - Integration with AgentOps API for MCP"""
+    import argparse
+    import asyncio
+
+    parser = argparse.ArgumentParser(
+        description="Provide MCP tools for interacting with the AgentOps API"
+    )
+    parser.add_argument("--api-url", type=str, default=DEFAULT_API_URL, 
+                        help=f"Base URL for AgentOps API (default: {DEFAULT_API_URL})")
+    
+    args = parser.parse_args()
+    
+    print(f"Starting AgentOps API MCP server with API URL: {args.api_url}")
+    asyncio.run(serve(args.api_url))
+
+
+if __name__ == "__main__":
+    main()

src/mcp_server_agentops_api/__main__.py

@@ -0,0 +1,5 @@
+# __main__.py
+
+from mcp_server_agentops_api import main
+
+main()