404.directory

404.directory

AI Agent 操作的风险预检。

在 AI Agent 使用第三方工具之前，404.directory 会检查可用证据，并返回 allow、review 或 block 决策。

面向将 Agent 接入外部工具、并希望在执行前进行明确风险检查的开发者。 这是一项实验性预检服务，其决策取决于可用证据。

从一个操作开始

连接你的 Agent，可使用 Codex、Cursor、Claude Code 或 MCP SDK。

工具工作流如下：

A proposed third-party tool action
  → provider verification + live checks + available usage evidence
  → allow / review / block

对已注册的第三方工具操作使用 evaluate_tool_risk。单独的 evaluate_prediction_market 工作流会检查结算措辞、时间安排、公开订单簿流动性、调用方观察到的资格条件以及执行模式。它不会预测赢家，也不会下单。

官方文档搜索、部署验证和精选只读 MCP 网关是辅助功能。完整的 API 映射请参阅产品层。

第一次尝试？ 加入前 10 位用户激活试点，并报告你的客户端、任务类别和失败阶段。

安装

Agent 可读取的安装说明：llms-install.md

在 Codex、Claude Code、Cursor、Cline 或其他 Agent Skills 客户端中安装 Agent Skill：

npx skills add MM-sheng/404-directory --skill use-404-directory -g -y

该仓库也符合 Agent Plugins 1.0 标准：兼容的客户端会从 skills/ 中发现 Agent Skill，并通过根目录下的 mcp.json 连接到保留身份的托管 Streamable HTTP 服务。该桥接会在客户端管理的 PLUGIN_DATA 目录中创建一个随机 ID。原始 ID 保留在本地；只有在工具调用成功后，服务才会存储 HMAC 摘要。

Claude Code 和 Cowork 使用 .claude-plugin/ 中的原生清单。它会通过 Claude 的持久化插件数据目录加载相同的 Skill 和保留身份的桥接，因此更新不会改变安装身份。

在官方目录提交审核期间，可直接在 Claude Code 中安装：

/plugin marketplace add MM-sheng/404-directory
/plugin install 404-directory@404-directory

产品层

层级	用途	接口
一方执行	在此进程中运行一方工具	GET /tools、POST /understand、POST /verify/web、MCP 工具
精选远程执行	搜索并调用经批准的只读远程 MCP 工具	MCP search_official_docs / inspect_tool_server / invoke_registered_tool
生态目录 + 信任	注册 / 验证 / 信任 / 搜索第三方工具	/v1/*、MCP search_tools / get_tool / compare_tools / get_trust_score
情境化风险预检	判断 Agent 现在是否应继续操作	MCP evaluate_tool_risk / report_tool_outcome、REST /v1/evaluations/*
预测市场预检	在操作前检查结算和执行风险	MCP evaluate_prediction_market / report_prediction_market_outcome、REST /v1/prediction-markets/evaluations/*

当前产品有意保持精简：预检一项预测市场决策或一项已注册的第三方工具操作，然后记录有限范围内的结果。未来的身份、声誉、担保和保险层仍是假设，只有真实的外部 Agent 使用情况才能验证这些设想。

当前一方工具

工具	端点	适用场景
understand_webpage	POST /understand	理解普通网页（实体、状态、操作），且没有 Agent 原生 API
verify_web	POST /verify/web	在有人声称已部署／更新后，独立验证公开网站

Agent 发现 API（/v1）

需要目录后端（DATABASE_URL 指向 Postgres，或在 CATALOG_MEMORY_FALLBACK=true 时使用内存回退）。

# Bootstrap admin token (required in production; auto-generated in local/dev)
export REGISTRY_ADMIN_TOKEN=change-me-to-a-long-secret

# Register a tool (pending quarantine until ownership + protocol verification)
curl -sS http://127.0.0.1:4040/v1/tools \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $REGISTRY_ADMIN_TOKEN" \
  -d '{
    "name":"btc_analyzer",
    "description":"Analyze BTC market signals for agents",
    "capabilities":["btc","market-analysis"],
    "protocol":"mcp",
    "endpoint":"https://example.com/mcp",
    "category":"finance",
    "provider":{"name":"Example Labs","identity":{"type":"domain","value":"example.com"}}
  }'
# Response includes provider_api_key once — store it for ownership + further writes.

# Search (active tools only)
curl -sS 'http://127.0.0.1:4040/v1/tools/search?capability=btc&trust_threshold=0.2'

# Trust profile
curl -sS http://127.0.0.1:4040/v1/tools/btc_analyzer/trust

内存和 PostgreSQL 中的目录关键词搜索均使用 catalog-lexical-v2。 可尝试 q=official%20documentation 或 q=OpenAI%20docs；词语无需相邻。 所有有意义的词都必须出现在名称、描述、能力、类别或提供方字段中。 完全匹配的名称优先，然后是词法相关性、现有信任证据和使用情况。能力／协议／类别／信任筛选条件仍为必需条件，公开搜索仍会排除已隔离和已暂停的工具。

无匹配项时会返回 count: 0、search.result_status: "no_matches"，以及指向 MCP list_capabilities／REST /v1/capabilities 的恢复步骤。空的 MCP 搜索是有效响应，但会记录为 no_matches，而非成功激活 Agent。这并不意味着任务不可能完成。搜索既不会执行工具，也不能证明工具安全；请对选定的确切 slug 执行预检。参见搜索语义和验收结果。

信任档案维度（v1 算法，可扩展的 factors JSON）：

• 所有权／可用性／兼容性／安全性／使用情况 → overall_score

可通过 POST /v1/evaluations 执行情境预检；可通过 GET /v1/evaluations/:id 读取公开回执。可使用评估时返回的一次性令牌，通过 POST /v1/evaluations/:id/outcome 附加一条有范围限制的结果记录。仅存储令牌哈希，自行报告的结果绝不会直接提高信任度。旧版通用接口 POST /v1/receipts 仍处于禁用状态，因为未绑定身份的匿名提交会污染信任度。

可直接复制的 Agent 触发策略和示例： docs/AGENT_RISK_PREFLIGHT.md

隐私安全的产品验证可通过公开接口 GET /v1/metrics/risk-evaluations 获取：评估量、决策分布、结果报告率和行为变化率，不含提示词或原始身份信息。

预测市场工作流的文档见 docs/PREDICTION_MARKET_PREFLIGHT.md。 其隐私安全的聚合指标可通过以下接口获取： GET /v1/metrics/prediction-market-evaluations。

MCP 发现工具

启用目录后，MCP 还会提供以下工具：

• evaluate_prediction_market
• report_prediction_market_outcome
• evaluate_tool_risk
• report_tool_outcome
• search_tools
• get_tool
• compare_tools
• get_trust_score
• recommend_tools
• list_capabilities
• get_capability_graph
• search_official_docs
• inspect_tool_server
• invoke_registered_tool

以及现有的可执行工具。

evaluate_prediction_market 是首次使用的主要入口：一次调用即可评估确切的 Polymarket 市场在结算、流动性、资格和执行方面的风险，不进行预测或交易。evaluate_tool_risk 是第二个切入点，用于 Agent 安装或调用不熟悉的第三方工具之前。search_official_docs 仍是辅助入口，返回范围受限的一方引用，而非原始提供方索引。任意 URL、经过身份验证的服务、非活动条目、未经验证的提供方和破坏性工具都会被拒绝。远程结果有范围限制，并会明确标记为不可信数据。

MCP 任务提示词

提供 MCP 提示词的客户端还会收到四个面向任务的起点：

• preflight-prediction-market — 将确切的市场和计划采取的操作转换为一次 evaluate_prediction_market 调用；
• evaluate-agent-tool — 查找目录候选项，调用上下文风险预检，并要求返回 allow、review 或 block 结果；
• research-official-docs — 将实际的技术问题转换为一次 search_official_docs 调用；
• verify-public-deployment — 将具体的公开部署声明转换为一次 verify_web 调用。

渲染或打开提示词不计入 1,000 个 Agent 的目标。每个模板都明确要求工具返回非错误结果，并实质性地回答用户任务。服务仅记录汇总的 prompts/list 和 prompts/get 激活阶段，从不记录提示词参数或任务文本。

MCP 提示词参数是字符串。evaluate-agent-tool 要求提供明确的 permissions 参数，例如 "public_network,credentials" 或 JSON 数组字符串 '["public_network","credentials"]'。仅当操作无需任何权限时才使用 "[]"。缺失、格式错误或未知的权限都会被拒绝，不会被默认为安全。此字符串编码仅适用于 prompts/get；evaluate_tool_risk 仍接受 JSON 数组。

直接集成交易 Agent 的相关信息，请参阅 docs/AGENT_INTEGRATION_QUICKSTART.md。 隐私安全的首批 10 个 Agent 群组流程记录在 docs/FIRST_10_AGENT_PILOT.md 中。

能力图谱

Agent 可以探索共享能力边，并获取相关工具推荐：

curl -sS http://127.0.0.1:4040/v1/capabilities | jq
curl -sS http://127.0.0.1:4040/v1/graph/capabilities | jq '.edges[:3]'
curl -sS http://127.0.0.1:4040/v1/tools/verify_web/related | jq

相似度采用能力集的 Jaccard 指数，并对匹配的协议/类别给予小幅加权（cap_v1）。这是长期能力图谱的雏形。

快速开始

npm install
npx playwright install chromium
cp .env.example .env
npm run dev

默认值：http://127.0.0.1:4040

使用 Postgres：

docker compose up -d postgres
export DATABASE_URL=postgres://404:[email protected]:5432/404
npm run db:migrate
npm run dev

启动时，第一方工具会被植入目录（SEED_FIRST_PARTY_TOOLS=true），因此 GET /v1/tools/search?capability=web-verification 会返回 verify_web。 当 SEED_CURATED_MCP_SERVERS=true 时，六个经运营方审核的公开 MCP 服务也会作为待处理条目植入。验证工作进程会在这些服务变为可发现或可执行之前，执行实时 MCP 准入检查。

验证工作进程

• 默认值：VERIFICATION_WORKER_MODE=inline（在 HTTP 进程内循环运行）
• 为生产负载拆分运行：

export VERIFICATION_WORKER_MODE=external
npm run worker:verify

提供方所有权（DNS TXT 或 GitHub 简介）

# Domain provider
curl -sS -X POST http://127.0.0.1:4040/v1/providers/example-labs/ownership/challenge
# Publish DNS: _404-directory.example.com TXT "404-directory-verify=<token>"
curl -sS -X POST http://127.0.0.1:4040/v1/providers/example-labs/ownership/verify

# GitHub provider (identity.type=github)
curl -sS -X POST http://127.0.0.1:4040/v1/providers/octo/ownership/challenge
# Put "404-directory-verify=<token>" in the public GitHub profile bio
curl -sS -X POST http://127.0.0.1:4040/v1/providers/octo/ownership/verify

所有权评分梯度：第一方 1.0 → dns_txt 0.95 → github_bio 0.9 → 通用已验证 0.8 → 未验证 0.35。

npm test
npm run typecheck
npm run build
npm start

Agent 发现（404 个服务工具）

服务清单与已注册的生态目录彼此独立：

界面	含义
MCP tools/list、GET /tools	相同的已启用、可调用的 404 服务工具（启用默认原生工具、目录和网关时为 16 个）
GET /tools/:name	实际的 MCP 参数架构、安全注释，以及明确的 MCP / REST 调用路由
GET /v1/tools/search	已注册的目标记录，包括预置的第一方和第三方工具；匹配结果并不代表获准执行
GET /v1/capabilities	生态记录的能力标签，而非可调用的 404 函数列表

主页、安装指南、文档、服务卡片和发现元数据 均根据启动时实际的 MCP 注册信息生成已启用的工具清单。 三个网关工具（search_official_docs、inspect_tool_server、 invoke_registered_tool）仅支持 MCP：其元数据中的 invocation.rest: null。 对于其他工具，请遵循声明的 REST 路径和参数映射， 不要假设 /tools/:name 会执行工具。HTTP 契约保留在 /openapi.json 中； MCP 元数据架构遵循 MCP 的 JSON Schema 方言，而非 OpenAPI 3 的架构方言。更改注册信息/配置后，请重启服务。

有关验证、兼容性说明和仅限本地的交付边界，请参阅发现一致性审计。

curl -sS http://127.0.0.1:4040/tools | jq
curl -sS http://127.0.0.1:4040/tools/understand_webpage | jq
curl -sS http://127.0.0.1:4040/openapi.json | jq '.paths | keys'
curl -sS http://127.0.0.1:4040/mcp-info | jq
curl -sS http://127.0.0.1:4040/llms.txt
curl -sS http://127.0.0.1:4040/health

主页（GET /）刻意保持精简：品牌、标语、工具名称，以及指向 Tools / MCP / OpenAPI / Docs / Health 的链接。

REST 示例

curl -sS http://127.0.0.1:4040/understand \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com"}'

curl -sS http://127.0.0.1:4040/verify/web \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com","expected_status":200,"expected_text":"Example Domain"}'

verify_web 会在 checks 中返回简洁的布尔值，并提供结构化的 evidence 对象，其中包含请求的 URL 和最终 URL、HTTP 状态比较、预期文本匹配、 TLS 验证、完整的重定向链、时间戳，以及明确的声明 → 证据路径。

目前，工具执行公开且免费。速率限制使用 Vercel 可信客户端 IP 标头（或本地套接字 IP）。

MCP

Streamable HTTP（与 REST 使用同一进程）

将 MCP 客户端指向 https://404.directory/mcp（或本地的 http://127.0.0.1:4040/mcp）。

托管端点也可以直接用作 OpenAI Responses API 远程 MCP 工具。可在 llms-install.md 中获取可直接复制的载荷，其中包含隐私安全的安装令牌；另请参阅 OpenAI 官方 MCP 指南。

若要符合已验证计数的条件，请在 X-404-Agent-ID 中发送稳定、随机且不含个人信息的 标识符。服务器只会持久化 HMAC 摘要，不会保存原始 ID、提示词、参数或结果。 成功调用是必要条件，但本身不会计入：还必须单独接受来自独立运营方的证据。 X-404-Source 是可选的小写归因标签。已验证的公开进度可通过 GET /v1/metrics/verified-agents 查看；未验证的安装诊断仍可通过 GET /v1/metrics/agents 查看。 完整的客户端示例见 https://404.directory/connect。

OpenAI Responses 未说明支持任意远程 MCP 请求标头。其示例改为使用受支持的 MCP authorization 字段， 以及生成的 agent:<uuid>@<source> 安装令牌。404.directory 仅接受这种 严格限定且不含个人信息的格式作为 Agent 标识；其他无关的 OAuth bearer 令牌仍被视为匿名，绝不会被当作 Agent ID。 隐私安全的激活漏斗可通过 GET /v1/metrics/activation 获取。它会报告观察到的 Connect 页面浏览量和安装器点击量，以及去重后的外部 Agent 数量，这些 Agent 已完成 MCP initialize、 tools/list、prompts/list、prompts/get、尝试调用工具、调用工具失败或成功执行工具。按来源划分的输出会分别统计调用率、调用成功率、提示词到成功率，以及端到端激活率。漏斗中的每个阶段仅用于诊断。成功执行是必要条件，但若没有单独通过活跃独立运营者证据审核，则不计入 1,000 个 Agent 的目标。激活事件中不会存储提示词名称和参数。漏斗中不会存储原始 Agent ID、IP、提示词、参数或结果。

GET /v1/metrics/verified-agents 会报告已验证 Agent 的隐私安全 7/30 天留存率。只有在完整观察窗口结束后，Agent 才符合条件；且只有在之后的另一个 UTC 日再次成功，才会计为留存。 GET /v1/metrics/agents 会按安全客户端标签保留未经验证的安装诊断数据。GET /v1/metrics/reliability?days=30 会按工具、已注册的提供方、客户端和归因来源汇总外部执行证据，包括样本量、成功率、P50/P95 延迟、结果数量以及有限的错误分类。匿名外部执行可用于评估可靠性，但绝不会计入 1,000 个已验证 Agent 的目标。

官方 MCP Registry 条目还会将 X-404-Agent-ID 声明为安装输入，并将 X-404-Source 的默认值设为 official-registry，以便兼容的客户端保留隐私安全的身份标识，而不是悄然创建匿名使用记录。不带这两个标头也仍可使用此服务。

动态安装页面还会生成一键式 VS Code / GitHub Copilot Agent 链接，其中已嵌入唯一的非个人 ID：

https://404.directory/connect?source=github

客户端或目录可以显示同域名、无脚本的服务图标： https://404.directory/icon.svg。

对于只接受 stdio 启动命令的客户端或目录，请使用可保留身份标识的托管桥接程序。它会在用户常用的应用程序数据目录中为每个 MCP 客户端创建一个随机 Agent ID，并在重启后继续使用该 ID：

{
  "mcpServers": {
    "404-directory": {
      "command": "npx",
      "args": ["-y", "@mmvv1638/404-directory-mcp"]
    }
  }
}

无需账户或 API 密钥。此桥接程序无需依赖项，只会将 MCP JSON-RPC 流量转发到 https://404.directory/mcp。

Codex 支持在 ~/.codex/config.toml 中配置 MCP HTTP 标头：

[mcp_servers.404_directory]
url = "https://404.directory/mcp"
http_headers = { "X-404-Agent-ID" = "agent:REPLACE_WITH_A_STABLE_RANDOM_ID", "X-404-Source" = "codex" }

如果希望 Agent 安装记录保留隐私安全的身份标识，请勿只添加裸 MCP URL。请使用 https://404.directory/connect?source=github 中生成的 Codex 配置。

stdio

{
  "mcpServers": {
    "404-directory": {
      "command": "npm",
      "args": ["run", "mcp", "--silent"],
      "cwd": "/absolute/path/to/this/repo"
    }
  }
}

工具会从 Tool Registry 自动注册，无需为每个工具手动编写单独的 MCP 适配器。

添加工具

1. 实现处理程序和 Zod 输入／输出架构
2. 在 src/tools/definitions/ 中创建 ToolDefinition
3. 在 src/tools/create-registry.ts 中注册

REST、OpenAPI、/tools/:name 和 MCP 都会从 Registry 中获取该工具。请保持 /tools 简洁，以免发现成本随每个架构的增加而上升。

Cloud Run / 生产环境

生产环境运行在 Google Cloud Run 上。Dockerfile 使用 Node slim， 并且只安装 Chromium 的无头 Shell，使保留的 Artifact Registry 镜像 保持在 0.5 GiB 免费存储额度以内。

生产环境必须持久化目录数据。 如果未设置 DATABASE_URL， 且 CATALOG_MEMORY_FALLBACK=true（本地默认值），Registry / Trust / 遥测数据会在每次冷启动时消失。另外：基于请求的 Cloud Run 不能 可靠地运行进程内 setInterval 工作线程——请使用外部工作线程。

# 1) Managed Postgres (Cloud SQL / Neon / etc.) + migrate
export DATABASE_URL=postgres://...
npm run db:migrate

# 2) API service
gcloud run deploy directory-404 \
  --source . \
  --region asia-east1 \
  --allow-unauthenticated \
  --execution-environment gen2 \
  --cpu 1 \
  --memory 2Gi \
  --concurrency 4 \
  --min-instances 0 \
  --max-instances 1 \
  --timeout 120 \
  --port 8080 \
  --set-env-vars "DATABASE_URL=${DATABASE_URL},CATALOG_MEMORY_FALLBACK=false,VERIFICATION_WORKER_MODE=external,REGISTRY_REQUIRE_AUTH=true,REGISTRY_ADMIN_TOKEN=${REGISTRY_ADMIN_TOKEN},PUBLIC_BASE_URL=https://404.directory,HOST=0.0.0.0,PORT=8080"

# 3) Independent verification worker (Cloud Run Job + Scheduler, or always-on)
#    VERIFICATION_WORKER_MODE=external on the API; run:
#    npm run worker:verify

Registry 写入 API（POST /v1/tools、所有权挑战/验证、手动 验证）需要 Authorization: Bearer <REGISTRY_ADMIN_TOKEN|provider_api_key>。 新提供方会收到一次性 provider_api_key。搜索默认只返回 status=active 的工具——待处理工具会被隔离。

将 cloudrun.cleanup-policy.json 应用于源代码部署所用的 Artifact Registry 代码库，以免已被取代且未标记的镜像不断累积并产生存储费用。

本地 Docker 仍可使用：

cp .env.example .env
docker compose up --build -d

生产环境加固说明：

• 将 BROWSER_EGRESS_ALLOWED_PORTS 的范围设得严格（默认值为 80,443）
• 根据流量调整 RATE_LIMIT_* 以及验证/浏览器超时
• 工具执行的 TOOL_RATE_LIMIT_MAX 限制比发现操作更严格
• 远程 MCP 网关仅限运营方筛选、提供方已验证、处于活跃状态、无需身份验证的服务，以及明确列出的只读工具
• 网关参数上限为 16 KiB；结果大小和外部调用时长分别受 MCP_GATEWAY_MAX_RESULT_BYTES 和 MCP_GATEWAY_TIMEOUT_MS 限制
• 配置 DATABASE_URL 时，将 CATALOG_MEMORY_FALLBACK=false
• 在无服务器环境中，优先使用 VERIFICATION_WORKER_MODE=external

安全边界

• 仅允许 HTTP(S)；拒绝 URL 凭据
• 拒绝解析到私有/环回/链路本地/保留地址的 DNS 结果
• verify_web 会将每个连接固定到通过 DNS 验证的确切公网 IP，然后对每次重定向跳转重新解析并验证。仅对主机名发送 TLS SNI；IP 字面量 URL（例如 https://1.1.1.1）不发送 SNI，而是针对 IP 验证证书
• verify_web 限制响应正文大小；在所有环境中均拒绝 198.18.0.0/15 和其他保留网段
• understand_webpage 会重新解析并验证每个浏览器请求，但 Chromium 请求会经由仅限环回地址的正向代理。该代理会解析目标地址、拒绝私有/保留地址和不允许的端口，然后连接到通过验证的确切 IP。 Chromium 的隐式环回绕过和 QUIC 已禁用，同时会阻止未经过代理的 WebRTC UDP 流量。浏览器上下文还会设置 serviceWorkers: "block"。 如果托管平台支持，仍建议使用提供方/网络出口防火墙作为独立的第二道防线
• 未预期的 500/MCP 执行错误会经过清理；完整详情保留在日志中
• 结构化工具日志包含路由、状态、时长和工具名称，不包含请求正文
• 响应包含请求 ID、Server-Timing、no-sniff/frame/referrer/permissions/CSP 标头；REST 工具结果使用 Cache-Control: no-store，而 MCP 流式传输使用 SDK 的 no-cache, no-transform 策略

目录结构

src/
  domain/          # catalog: registry, verification, trust, discovery, telemetry,
                   #          ownership, capability-graph, seed
  db/              # drizzle schema + migrate
  workers/         # standalone verification worker
  tools/           # first-party executable registry
  understand.ts    # understand_webpage service
  verify/          # verify_web implementation
  http/            # Fastify app, homepage, OpenAPI
  mcp/             # stdio + registry→MCP + discovery tools
  browser/         # Playwright collection
  security/        # SSRF / URL guards
drizzle/           # SQL migrations