ArchiveBox API-A2A | AG-UI | MCP

PyPI - License

PyPI - Wheel PyPI - Implementation

*版本：0.10.0*

概述

ArchiveBox API Python包装器和快速MCP服务器！

此存储库提供了一个Python包装器，用于与ArchiveBox API交互，从而实现对web归档功能的编程访问。它包括一个用于代理AI的模型上下文协议（MCP）服务器，增强了各种身份验证机制、用于可观察性和控制的中间件，以及用于基于策略的访问控制的可选Eunomia授权。

欢迎投稿！

所有API响应对象都是为响应调用自定义的。您可以在 parent.value.nested_value 格式或使用 parent.json() 以字典的形式获取响应。

特征：

认证：支持多种身份验证类型，包括无（禁用）、静态（内部令牌）、JWT、OAuth代理、OIDC代理和外部身份提供者的远程OAuth。
中间件：包括日志记录、计时、速率限制和错误处理，以实现稳健的服务器操作。
Eunomia授权：可选的基于策略的授权，带有嵌入式或远程Eunomia服务器集成。
资源：提供 instance_config 用于ArchiveBox配置。
提示：包括 cli_add_prompt 用于人工智能驱动的交互。

API

API调用：

认证
核心模型（快照、存档结果、标签）
CLI命令（添加、更新、计划、列表、删除）

如果您的API调用不受支持，您可以通过添加自定义端点或修改现有包装来扩展功能。

这些是当前支持的API终结点

主控程序

上面所有可用的API调用都包含在MCP工具中。您可以在下面找到这些工具及其相关标签。

MCP工具

函数名称	描述	标签
`get_api_token`	为给定的用户名和密码生成API令牌。	`authentication`
`check_api_token`	验证API令牌以确保其有效且未过期。	`authentication`
`get_snapshots`	检索快照列表。	`core`
`get_snapshot`	按abid或id获取特定快照	`core`
`get_archiveresults`	列出与这些筛选器匹配的所有ArchiveResult条目。	`core`
`get_tag`	通过id或abid获取特定标签	`core`
`get_any`	按abid获取特定的快照、ArchiveResult或标记	`core`
`cli_add`	执行archivebox add命令。	`cli`
`cli_update`	执行archivebox更新命令。	`cli`
`cli_schedule`	执行归档箱计划命令。	`cli`
`cli_list`	执行archivebox list命令。	`cli`
`cli_remove`	执行archivebox remove命令。	`cli`

A2A代理

架构：

---
config:
  layout: dagre
---
flowchart TB
 subgraph subGraph0["Agent Capabilities"]
        C["Agent"]
        B["A2A Server - Uvicorn/FastAPI"]
        D["MCP Tools"]
        F["Agent Skills"]
  end
    C --> D & F
    A["User Query"] --> B
    B --> C
    D --> E["Platform API"]

     C:::agent
     B:::server
     A:::server
    classDef server fill:#f9f,stroke:#333
    classDef agent fill:#bbf,stroke:#333,stroke-width:2px
    style B stroke:#000000,fill:#FFD600
    style D stroke:#000000,fill:#BBDEFB
    style F fill:#BBDEFB
    style A fill:#C8E6C9
    style subGraph0 fill:#FFF9C4

组件交互图

sequenceDiagram
    participant User
    participant Server as A2A Server
    participant Agent as Agent
    participant Skill as Agent Skills
    participant MCP as MCP Tools

    User->>Server: Send Query
    Server->>Agent: Invoke Agent
    Agent->>Skill: Analyze Skills Available
    Skill->>Agent: Provide Guidance on Next Steps
    Agent->>MCP: Invoke Tool
    MCP-->>Agent: Tool Response Returned
    Agent-->>Agent: Return Results Summarized
    Agent-->>Server: Final Response
    Server-->>User: Output

图形架构

此代理使用 pydantic-graph 智能路由和最佳上下文管理的编排。

---
title: Archivebox API Graph Agent
---
stateDiagram-v2
  [*] --> RouterNode: User Query
  RouterNode --> DomainNode: Classified Domain
  RouterNode --> [*]: Low confidence / Error
  DomainNode --> [*]: Domain Result

路由器节点：快速、轻便的LLM（例如。， nvidia/nemotron-3-super)它将用户的查询分类到一个专门的域中。
域节点：执行器节点。对于所选域，它动态设置环境变量，以暂时仅启用与该域相关的工具，从而创建高度集中的子代理（例如。， gpt-4o)以完成请求。这保留了LLM上下文并防止了工具幻觉。

用法

主控程序

MCP-CLI

短旗	长旗	描述
-h	--help	显示帮助信息
-t	--transport	传输方法：“stdio”、“http”或“sse”\[遗留\]（默认值：stdio）
-s	--host	HTTP传输的主机地址（默认值：0.0.0.0）
-p	--port	HTTP传输的端口号（默认值：8000）
	--auth-type	身份验证类型：“none”、“static”、“jwt”、“oauth代理”、“oidc代理”和“remote oauth”（默认值：none）
	--令牌jwks-uri	用于JWT验证的jwks uri
	--代币发行人	JWT验证发行人
	--令牌受众	JWT验证的受众
	--oauth上游授权端点	oauth代理的上游授权端点
	--oauth上游令牌端点	oauth代理的上游令牌端点
	--oauth上游客户端id	oauth代理的上游客户端id
	--oauth上游客户端机密	oauth代理的上游客户端机密
	--oauth基本url	oauth代理的基本url
	--oidc配置url	oidc配置url
	--oidc客户端id	oidc客户端id
	-oidc客户端机密	oidc客户端机密
	--oidc基本url	oidc代理的基本url
	--远程身份验证服务器	远程OAuth的逗号分隔的授权服务器列表
	--远程基本url	远程OAuth的基本url
	--允许的客户端重定向URI	逗号分隔的允许客户端重定向URI列表
	--eunomia type	eunomia授权类型：“无”、“嵌入式”、“远程”（默认值：无）
	--eunomia策略文件	嵌入式eunomia的策略文件（默认：mcp_policies.json）
	--eunomia远程url	远程eunomia服务器的url

用作MCP服务器

MCP服务器可以在两种模式下运行： stdio （用于本地测试）或 http （用于网络访问）。要启动服务器，请使用以下命令：

在stdio模式下运行（默认）：

archivebox-mcp --transport "stdio"

在HTTP模式下运行：

archivebox-mcp --transport "http" --host "0.0.0.0" --port "8000"

API基本用法

令牌身份验证

#!/usr/bin/python
# coding: utf-8
import archivebox_api

archivebox_url = ""
token = ""

client = archivebox_api.Api(
    url=archivebox_url,
    token=token
)

snapshots = client.get_snapshots()
print(f"Snapshots: {snapshots.json()}")

基本身份验证

#!/usr/bin/python
# coding: utf-8
import archivebox_api

username = ""
password = ""
archivebox_url = ""

client = archivebox_api.Api(
    url=archivebox_url,
    username=username,
    password=password
)

snapshots = client.get_snapshots()
print(f"Snapshots: {snapshots.json()}")

API密钥验证

#!/usr/bin/python
# coding: utf-8
import archivebox_api

archivebox_url = ""
api_key = ""

client = archivebox_api.Api(
    url=archivebox_url,
    api_key=api_key
)

snapshots = client.get_snapshots()
print(f"Snapshots: {snapshots.json()}")

SSL验证

#!/usr/bin/python
# coding: utf-8
import archivebox_api

username = ""
password = ""
archivebox_url = ""

client = archivebox_api.Api(
    url=archivebox_url,
    username=username,
    password=password,
    verify=False
)

snapshots = client.get_snapshots()
print(f"Snapshots: {snapshots.json()}")

将MCP服务器部署为服务

ArchiveBox MCP服务器可以使用Docker部署，具有可配置的身份验证、中间件和Eunomia授权。

使用Docker运行

docker pull archivebox/archivebox:latest

docker run -d \
  --name archivebox-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=none \
  -e EUNOMIA_TYPE=none \
  -e ARCHIVEBOX_URL=https://yourinstance.archivebox.com \
  -e ARCHIVEBOX_USERNAME=user \
  -e ARCHIVEBOX_PASSWORD=pass \
  -e ARCHIVEBOX_TOKEN=token \
  -e ARCHIVEBOX_API_KEY=api_key \
  -e ARCHIVEBOX_SSL_VERIFY=False \
  archivebox/archivebox:latest

对于高级身份验证（例如JWT、OAuth代理、OIDC代理、远程OAuth）或Eunomia，添加相关的环境变量：

docker run -d \
  --name archivebox-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=oidc-proxy \
  -e OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration \
  -e OIDC_CLIENT_ID=your-client-id \
  -e OIDC_CLIENT_SECRET=your-client-secret \
  -e OIDC_BASE_URL=https://your-server.com \
  -e ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/* \
  -e EUNOMIA_TYPE=embedded \
  -e EUNOMIA_POLICY_FILE=/app/mcp_policies.json \
  -e ARCHIVEBOX_URL=https://yourinstance.archivebox.com \
  -e ARCHIVEBOX_USERNAME=user \
  -e ARCHIVEBOX_PASSWORD=pass \
  -e ARCHIVEBOX_TOKEN=token \
  -e ARCHIVEBOX_API_KEY=api_key \
  -e ARCHIVEBOX_SSL_VERIFY=False \
  archivebox/archivebox:latest

使用Docker Compose

创建一个 docker-compose.yml 文件：

services:
  archivebox-mcp:
    image: archivebox/archivebox:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8004
      - TRANSPORT=http
      - AUTH_TYPE=none
      - EUNOMIA_TYPE=none
      - ARCHIVEBOX_URL=https://yourinstance.archivebox.com
      - ARCHIVEBOX_USERNAME=user
      - ARCHIVEBOX_PASSWORD=pass
      - ARCHIVEBOX_TOKEN=token
      - ARCHIVEBOX_API_KEY=api_key
      - ARCHIVEBOX_SSL_VERIFY=False
    ports:
      - 8004:8004

对于具有身份验证和Eunomia的高级设置：

services:
  archivebox-mcp:
    image: archivebox/archivebox:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8004
      - TRANSPORT=http
      - AUTH_TYPE=oidc-proxy
      - OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration
      - OIDC_CLIENT_ID=your-client-id
      - OIDC_CLIENT_SECRET=your-client-secret
      - OIDC_BASE_URL=https://your-server.com
      - ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/*
      - EUNOMIA_TYPE=embedded
      - EUNOMIA_POLICY_FILE=/app/mcp_policies.json
      - ARCHIVEBOX_URL=https://yourinstance.archivebox.com
      - ARCHIVEBOX_USERNAME=user
      - ARCHIVEBOX_PASSWORD=pass
      - ARCHIVEBOX_TOKEN=token
      - ARCHIVEBOX_API_KEY=api_key
      - ARCHIVEBOX_SSL_VERIFY=False
    ports:
      - 8004:8004
    volumes:
      - ./mcp_policies.json:/app/mcp_policies.json

运行服务：

docker-compose up -d

配置 `mcp.json` AI集成

建议：将机密存储在环境变量中，并在JSON文件中查找。

仅用于测试：纯文本存储也可以工作，尽管不推荐。

{
  "mcpServers": {
    "archivebox": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "archivebox-api",
        "archivebox-mcp",
        "--transport",
        "${TRANSPORT}",
        "--host",
        "${HOST}",
        "--port",
        "${PORT}",
        "--auth-type",
        "${AUTH_TYPE}",
        "--eunomia-type",
        "${EUNOMIA_TYPE}"
      ],
      "env": {
        "ARCHIVEBOX_URL": "https://yourinstance.archivebox.com",
        "ARCHIVEBOX_USERNAME": "user",
        "ARCHIVEBOX_PASSWORD": "pass",
        "ARCHIVEBOX_TOKEN": "token",
        "ARCHIVEBOX_API_KEY": "api_key",
        "ARCHIVEBOX_VERIFY": "False",
        "TOKEN_JWKS_URI": "${TOKEN_JWKS_URI}",
        "TOKEN_ISSUER": "${TOKEN_ISSUER}",
        "TOKEN_AUDIENCE": "${TOKEN_AUDIENCE}",
        "OAUTH_UPSTREAM_AUTH_ENDPOINT": "${OAUTH_UPSTREAM_AUTH_ENDPOINT}",
        "OAUTH_UPSTREAM_TOKEN_ENDPOINT": "${OAUTH_UPSTREAM_TOKEN_ENDPOINT}",
        "OAUTH_UPSTREAM_CLIENT_ID": "${OAUTH_UPSTREAM_CLIENT_ID}",
        "OAUTH_UPSTREAM_CLIENT_SECRET": "${OAUTH_UPSTREAM_CLIENT_SECRET}",
        "OAUTH_BASE_URL": "${OAUTH_BASE_URL}",
        "OIDC_CONFIG_URL": "${OIDC_CONFIG_URL}",
        "OIDC_CLIENT_ID": "${OIDC_CLIENT_ID}",
        "OIDC_CLIENT_SECRET": "${OIDC_CLIENT_SECRET}",
        "OIDC_BASE_URL": "${OIDC_BASE_URL}",
        "REMOTE_AUTH_SERVERS": "${REMOTE_AUTH_SERVERS}",
        "REMOTE_BASE_URL": "${REMOTE_BASE_URL}",
        "ALLOWED_CLIENT_REDIRECT_URIS": "${ALLOWED_CLIENT_REDIRECT_URIS}",
        "EUNOMIA_TYPE": "${EUNOMIA_TYPE}",
        "EUNOMIA_POLICY_FILE": "${EUNOMIA_POLICY_FILE}",
        "EUNOMIA_REMOTE_URL": "${EUNOMIA_REMOTE_URL}"
      },
      "timeout": 200000
    }
  }
}

CLI参数

这 archivebox-mcp 命令支持以下CLI选项进行配置：

--transport：运输方式(stdio, http, sse)\[默认值： http\]
--host：HTTP传输的主机地址\[默认值： 0.0.0.0\]
--port：HTTP传输的端口号\[默认值： 8000\]
--auth-type：身份验证类型(none, static, jwt, oauth-proxy, oidc-proxy, remote-oauth)\[默认值： none\]
--token-jwks-uri：用于JWT验证的JWKS URI
--token-issuer：JWT验证的发行人
--token-audience：JWT验证的受众
--oauth-upstream-auth-endpoint：OAuth代理的上游授权端点
--oauth-upstream-token-endpoint：OAuth代理的上游令牌端点
--oauth-upstream-client-id：OAuth代理的上游客户端ID
--oauth-upstream-client-secret：OAuth代理的上游客户端密钥
--oauth-base-url：OAuth代理的基本URL
--oidc-config-url：OIDC配置URL
--oidc-client-id：OIDC客户端ID
--oidc-client-secret：OIDC客户端机密
--oidc-base-url：OIDC代理的基本URL
--remote-auth-servers：以逗号分隔的远程OAuth授权服务器列表
--remote-base-url：远程OAuth的基本URL
--allowed-client-redirect-uris：允许的客户端重定向URI的逗号分隔列表
--eunomia-type：Eunomia授权类型(none, embedded, remote)\[默认值： none\]
--eunomia-policy-file：嵌入式Eunomia的策略文件\[默认值： mcp_policies.json\]
--eunomia-remote-url：远程Eunomia服务器的URL

中间件

MCP服务器包括以下内置中间件，以增强功能：

错误处理中间件：提供全面的错误记录和转换。
RateLimiting中间件：使用令牌桶算法限制请求频率（10个请求/秒，突发容量为20）。
定时中间件：跟踪请求的执行时间。
日志中间件：记录所有请求和响应以确保可观察性。

Eunomia授权

服务器支持基于策略的访问控制的可选Eunomia授权：

残疾人(none)：没有授权检查。
嵌入式(embedded)：使用本地策略文件运行嵌入式Eunomia服务器(mcp_policies.json 默认情况下）。
远程(remote)：连接到外部Eunomia服务器以进行集中策略决策。

要配置Eunomia策略，请执行以下操作：

# Initialize a default policy file
eunomia-mcp init

# Validate the policy file
eunomia-mcp validate mcp_policies.json

A2A-CLI

端点

Web 用户界面: http://localhost:8000/ （如果启用）
A2A: http://localhost:8000/a2a （发现： /a2a/.well-known/agent.json)
AG-UI: http://localhost:8000/ag-ui （职位）

短旗	长旗	描述
-h	--help	显示帮助信息
	--host	绑定服务器的主机（默认值：0.0.0.0）
	--port	绑定服务器的端口（默认值：9000）
	--reload	启用自动重新加载
	--provider	LLM提供者：“openai”、“anthropic”、“google”、“huggingface”
	--型号id	LLM型号id（默认：nvidia/nemotron-3-super）
	--基本url	LLM基本url（适用于OpenAI兼容的提供者）
	--api-key	LLM api密钥

||--mcp url|mcp服务器url（默认值：http://localhost:8000/mcp) | ||--web|启用Pydantic AI web UI | False（环境：Enable_web_UI）|

安装Python包

python -m pip install archivebox-api[all]

存储库所有者

MCP配置示例

1.标准IO（stdio）部署

{
  "mcpServers": {
    "archivebox-api": {
      "command": "uv",
      "args": [
        "run",
        "archivebox-mcp"
      ],
      "env": {
        "AGENT_DESCRIPTION": "",
        "AGENT_SYSTEM_PROMPT": "",
        "ARCHIVEBOX_API_KEY": "",
        "ARCHIVEBOX_PASSWORD": "",
        "ARCHIVEBOX_TOKEN": "",
        "ARCHIVEBOX_URL": "",
        "ARCHIVEBOX_USERNAME": "",
        "ARCHIVEBOX_VERIFY": "",
        "AUTHENTICATIONTOOL": "True",
        "CLITOOL": "True",
        "CORETOOL": "True",
        "DEFAULT_AGENT_NAME": "",
        "MISCTOOL": "True"
      }
    }
  }
}

2.流式HTTP（SSE）部署

{
  "mcpServers": {
    "archivebox-api": {
      "command": "uv",
      "args": [
        "run",
        "archivebox-mcp",
        "--transport",
        "http",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "AGENT_DESCRIPTION": "",
        "AGENT_SYSTEM_PROMPT": "",
        "ARCHIVEBOX_API_KEY": "",
        "ARCHIVEBOX_PASSWORD": "",
        "ARCHIVEBOX_TOKEN": "",
        "ARCHIVEBOX_URL": "",
        "ARCHIVEBOX_USERNAME": "",
        "ARCHIVEBOX_VERIFY": "",
        "AUTHENTICATIONTOOL": "True",
        "CLITOOL": "True",
        "CORETOOL": "True",
        "DEFAULT_AGENT_NAME": "",
        "MISCTOOL": "True"
      }
    }
  }
}

ArchiveBox API

快速接入

详细介绍

ArchiveBox API-A2A | AG-UI | MCP

概述

特征：

API

API调用：

主控程序

MCP工具

A2A代理

架构：

组件交互图

图形架构

用法

主控程序

MCP-CLI

用作MCP服务器

在stdio模式下运行（默认）：

在HTTP模式下运行：

API基本用法

将MCP服务器部署为服务

使用Docker运行

使用Docker Compose

配置 `mcp.json` AI集成

CLI参数

中间件

Eunomia授权

A2A-CLI

端点

安装Python包

存储库所有者

MCP配置示例

1.标准IO（stdio）部署

2.流式HTTP（SSE）部署

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

ArchiveBox API

快速接入

详细介绍

ArchiveBox API-A2A | AG-UI | MCP

概述

特征：

API

API调用：

主控程序

MCP工具

A2A代理

架构：

组件交互图

图形架构

用法

主控程序

MCP-CLI

用作MCP服务器

在stdio模式下运行（默认）：

在HTTP模式下运行：

API基本用法

将MCP服务器部署为服务

使用Docker运行

使用Docker Compose

配置 mcp.json AI集成

CLI参数

中间件

Eunomia授权

A2A-CLI

端点

安装Python包

存储库所有者

MCP配置示例

1.标准IO（stdio）部署

2.流式HTTP（SSE）部署

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

配置 `mcp.json` AI集成