ArchiveBox API

Version: 0.0.2

ArchiveBox API Python Wrapper & Fast MCP Server!

This repository provides a Python wrapper for interacting with the ArchiveBox API, enabling programmatic access to web archiving functionality. It includes a Model Context Protocol (MCP) server for Agentic AI, enhanced with various authentication mechanisms, middleware for observability and control, and optional Eunomia authorization for policy-based access control.

Contributions are welcome!

All API Response objects are customized for the response call. You can access return values in a parent.value.nested_value format, or use parent.json() to get the response as a dictionary.

API Calls:

• Authentication

• Core Model (Snapshots, ArchiveResults, Tags)

• CLI Commands (add, update, schedule, list, remove)

If your API call isn't supported, you can extend the functionality by adding custom endpoints or modifying the existing wrapper.

These are the API endpoints currently supported

Features:

• Authentication: Supports multiple authentication types including none (disabled), static (internal tokens), JWT, OAuth Proxy, OIDC Proxy, and Remote OAuth for external identity providers.

• Middleware: Includes logging, timing, rate limiting, and error handling for robust server operation.

• Eunomia Authorization: Optional policy-based authorization with embedded or remote Eunomia server integration.

• Resources: Provides instance_config for ArchiveBox configuration.

• Prompts: Includes cli_add_prompt for AI-driven interactions.

MCP CLI

Using as an MCP Server

The MCP Server can be run in two modes: stdio (for local testing) or http (for networked access). To start the server, use the following commands:

Run in stdio mode (default):

Run in HTTP mode:

Basic API Usage

Token Authentication

Basic Authentication

API Key Authentication

SSL Verify

Deploy MCP Server as a Service

The ArchiveBox MCP server can be deployed using Docker, with configurable authentication, middleware, and Eunomia authorization.

Using Docker Run

For advanced authentication (e.g., JWT, OAuth Proxy, OIDC Proxy, Remote OAuth) or Eunomia, add the relevant environment variables:

Using Docker Compose

Create a docker-compose.yml file:

For advanced setups with authentication and Eunomia:

Run the service:

Configure mcp.json for AI Integration

Recommended: Store secrets in environment variables with lookup in the JSON file.

For Testing Only: Plain text storage will also work, although not recommended.

CLI Parameters

The archivebox-mcp command supports the following CLI options for configuration:

• --transport: Transport method (stdio, http, sse) [default: http]

• --host: Host address for HTTP transport [default: 0.0.0.0]

• --port: Port number for HTTP transport [default: 8000]

• --auth-type: Authentication type (none, static, jwt, oauth-proxy, oidc-proxy, remote-oauth) [default: none]

• --token-jwks-uri: JWKS URI for JWT verification

• --token-issuer: Issuer for JWT verification

• --token-audience: Audience for JWT verification

• --oauth-upstream-auth-endpoint: Upstream authorization endpoint for OAuth Proxy

• --oauth-upstream-token-endpoint: Upstream token endpoint for OAuth Proxy

• --oauth-upstream-client-id: Upstream client ID for OAuth Proxy

• --oauth-upstream-client-secret: Upstream client secret for OAuth Proxy

• --oauth-base-url: Base URL for OAuth Proxy

• --oidc-config-url: OIDC configuration URL

• --oidc-client-id: OIDC client ID

• --oidc-client-secret: OIDC client secret

• --oidc-base-url: Base URL for OIDC Proxy

• --remote-auth-servers: Comma-separated list of authorization servers for Remote OAuth

• --remote-base-url: Base URL for Remote OAuth

• --allowed-client-redirect-uris: Comma-separated list of allowed client redirect URIs

• --eunomia-type: Eunomia authorization type (none, embedded, remote) [default: none]

• --eunomia-policy-file: Policy file for embedded Eunomia [default: mcp_policies.json]

• --eunomia-remote-url: URL for remote Eunomia server

Middleware

The MCP server includes the following built-in middleware for enhanced functionality:

• ErrorHandlingMiddleware: Provides comprehensive error logging and transformation.

• RateLimitingMiddleware: Limits request frequency with a token bucket algorithm (10 requests/second, burst capacity of 20).

• TimingMiddleware: Tracks execution time of requests.

• LoggingMiddleware: Logs all requests and responses for observability.

Eunomia Authorization

The server supports optional Eunomia authorization for policy-based access control:

• Disabled (: No authorization checks.

• Embedded (: Runs an embedded Eunomia server with a local policy file (mcp_policies.json by default).

• Remote (: Connects to an external Eunomia server for centralized policy decisions.

To configure Eunomia policies:

Install Python Package