Eco Oracle

EcoOracle

EcoOracle是一个MCP服务器加注册表管道，用于回答许多R/Python包中的生态系统问题。 主要目标：让用户通过检索规范使用配方和API卡，在软件包转发之外构建新的脚本。

它的设计使包裹入职具有确定性：

• package repo选项 .ecosystem.yml
• 包CI发布 atlas-pack.tgz 释放标签 eco-atlas
• eco-registry 发现更新 registry.json 每夜的
• MCP服务器加载注册表并提供服务 eco_howto, eco_symbol, eco_packages, eco_where_used

规范注册表存储库： https://github.com/bbuchsbaum/eco-registry.

什么住在这里

• packages/eco-oracle-mcp：MCP服务器
• tools/eco_atlas_extract.R：提取符号/片段/边
• tools/eco_atlas_distill.mjs：将片段提取到微型卡中
• tools/eco-atlas.yml：构建和发布的包端工作流模板 atlas-pack.tgz
• eco-registry：注册表仓库和夜间发现工作流
• schemas：卡片、符号、边缘、清单、注册表的数据契约

端到端流程

1. 软件包回购包括 .ecosystem.yml.
2. 打包工作流构建图集文件并发布 atlas-pack.tgz 释放标签 eco-atlas.
3. eco-registry/.github/workflows/discover-registry.yml 每晚在 04:00 UTC （以及人工调度）。
4. 发现脚本扫描所有者存储库，查找 .ecosystem.yml，解析发布资产，并写入 eco-registry/registry.json.
5. MCP服务器从注册表刷新并在本地缓存图集包。
6. Claude/Codex会话调用MCP工具来生成外部脚本。

添加新包（交钥匙）

在目标包存储库中执行此操作。

使用代理的最快路径：

• 问： Add this package to the ecosystem
• 如果 eco-join 技能是可用的，它构建了所需的文件/工作流程。

从R开始的最快路径：

# install.packages("remotes")
remotes::install_github("bbuchsbaum/eco-oracle")
library(ecooracle)

# initial scaffold
ecooracle::use_ecooracle()

# refresh workflow/tool templates later without hand edits
ecooracle::use_ecooracle(overwrite = TRUE)

# or run commit/push/workflow/discovery without prompts
ecooracle::use_ecooracle(
  commit = TRUE,
  push = TRUE,
  run_workflow = TRUE,
  run_discovery = TRUE
)

# check local onboarding health
ecooracle::check_health()

1. 添加 .ecosystem.yml 在repo根目录：

ecosystem: true
package: mypkg
language: R
role: transform
tags: [domain-tag, canonicalization]
entrypoints:
  - mypkg::main_fn
  - mypkg::read_input
# optional overrides (defaults shown)
release_tag: eco-atlas
asset: atlas-pack.tgz

1. 将图集工具添加到包仓库中：

• 复制 tools/eco_atlas_extract.R
• 复制 tools/eco_atlas_distill.mjs
• 复制 .github/workflows/eco-atlas.yml 从 tools/eco-atlas.yml

如果你使用 ecooracle::use_ecooracle()，这些文件是为你搭建的。重新运行它 overwrite = TRUE 将现有包刷新为当前模板集。助手还会填充占位符 role/tags/entrypoints 从描述和名称，在交互会话中，它可以询问是否提交、推送、触发 eco-atlas.yml，并触发注册表发现。

1. 配置包机密：

• OPENAI_API_KEY 用于蒸馏步骤

1. 推至 main （或手动运行工作流）：

• 验证发布标签 eco-atlas 包含资产 atlas-pack.tgz

1. 等待注册表发现（每晚）或触发 discover-registry 手动输入 eco-registry.

手动触发器示例：

gh workflow run discover-registry.yml --repo bbuchsbaum/eco-registry

1. 验证包是否在注册表中：

cat eco-registry/registry.json

1. 验证MCP是否可以加载它：

node packages/eco-oracle-mcp/dist/index.js
# then call eco_refresh and eco_packages from your MCP client

正常运行时不需要手动编辑注册表。

手册提示：确切地把它们放在哪里

如果您希望获得特定于包的指导来提高检索质量，请将其放在包存储库中，而不是 eco-registry/registry.json.

硬性规定：

1. 不要手动编辑 eco-registry/registry.json 获取包装提示。
2. 夜发现改写 registry.json.
3. 手动编辑是暂时的，将丢失。

在包仓库的持久源代码位置添加提示：

1. .ecosystem.yml

- 集 role, tags, entrypoints

1. R/*.R

- 添加 # ECO:howto ... 规范代码段上方的标记

1. README.Rmd / vignettes/*.Rmd

- 为真实工作流添加规范代码围栏

1. manual_cards.jsonl （可选，确定性覆盖）

- 添加手写的微型卡，并将其合并到最终文件中 atlas/cards.jsonl - 如果 id 与生成的卡id冲突，手动卡获胜

手动卡片档案合同：

1. 文件路径： manual_cards.jsonl 在包仓库根目录（默认；用覆盖 ECO_ATLAS_MANUAL_CARDS_PATH)
2. 每行一个JSON对象
3. 每条记录的必填字段：

- q, a, recipe, symbols

1. 可选字段：

- id, tags, package, language, sources

示例 manual_cards.jsonl 线路：

{"id":"manual.bidser.load_project","q":"How do I load a BIDS project in R?","a":"Use bidser::bids_project() on the dataset root, then inspect scans with func_scans().","recipe":"library(bidser)\nproj <- bidser::bids_project('/path/to/bids')\nscans <- bidser::func_scans(proj)","symbols":["bidser::bids_project","bidser::func_scans"],"tags":["bids","ingest"]}

示例 # ECO:howto 代码片段：

# ECO:howto How do I load a BIDS project?
library(bidser)
proj <- bidser::bids_project("/path/to/bids")
scans <- bidser::func_scans(proj)

什么会被自动化覆盖：

1. eco-registry/registry.json 通过发现而再生。
2. atlas/cards.jsonl 和释放 atlas-pack.tgz 由包图集工作流重新生成。

哪些内容不会被覆盖：

1. .ecosystem.yml 在包仓库中提交。
2. # ECO:howto 在包仓库中提交的标记和包文档。

手动提示操作流程：

1. 在包仓库中提交提示更改。
2. 运行/推送包 eco-atlas 工作流程如此新颖 atlas-pack.tgz 已出版。
3. 等待夜间发现（或手动触发）。
4. 跑 eco_refresh 在客户端验证行为 eco_howto / eco_symbol.

注册表自动化设置（一次完成 eco-registry)

将这些设置在 eco-registry GitHub仓库：

1. 秘密： GH_ORG_PAT

• 令牌必须读取目标所有者存储库并推送到 eco-registry

1. 变量： ECO_OWNER

• 扫描的所有者、组织或用户（例如 bbuchsbaum)

1. 可选变量： ECO_ORG

• 向后兼容回退

Discovery同时支持GitHub组织和用户。

在本地运行MCP服务器

来自此repo：

npm install
npm run build --workspace=packages/eco-oracle-mcp
node packages/eco-oracle-mcp/dist/index.js

环境：

• ECO_REGISTRY_URL 或 ECO_REGISTRY_PATH （至少设置一个）
• ECO_GITHUB_TOKEN （可选，私有发布资产需要）
• ECO_CACHE_DIR （可选，默认 ~/.cache/eco-oracle)
• ECO_REFRESH_SECS （可选，默认 600)

使用克劳德代码

用户范围：

claude mcp add --transport stdio eco-oracle --scope user -- npx -y eco-oracle-mcp

项目范围(.mcp.json):

{
  "mcpServers": {
    "eco-oracle": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "eco-oracle-mcp"],
      "env": {
        "ECO_REGISTRY_URL": "https://raw.githubusercontent.com/bbuchsbaum/eco-registry/main/registry.json",
        "ECO_GITHUB_TOKEN": "${ECO_GITHUB_TOKEN}"
      }
    }
  }
}

复制粘贴指令：生态系统优先（兼容哦，我的克劳德）

使用此 CLAUDE.md, AGENTS.md，或作为新克劳德/食品法典委员会会议的第一条信息：

## Internal package policy (eco-oracle MCP only)

This policy refers only to the `eco-oracle` MCP server.
Do not activate or invoke any other skill/mode (including `oh-my-claudecode:ecomode`) unless the user explicitly asks.

For R code, prefer ecosystem packages discovered via eco-oracle MCP.
Workflow is mandatory:

1. Call `eco_howto` first for each "How do I...?" subtask.
2. Call `eco_symbol` for each function you plan to use.
3. Use ecosystem packages/functions in final code.

Do not introduce non-ecosystem packages (for example `RNifti`, `oro.nifti`, `ANTsR`) unless:
1. eco-oracle returns no viable result, and
2. you explicitly ask for user approval before using external packages.

When answering, include:
1. `Ecosystem packages used: ...`
2. `Functions used: ...`
3. `Fallback needed: yes/no`

快速提示以强化任何新会话中的行为：

Use eco-oracle MCP as source of truth. Do not enable oh-my-claude modes/skills unless I explicitly request them. Ecosystem-only solution unless no match exists; if no match, ask me before using external packages.

快捷会话开启器（等效）：

Enter ecosystem mode.

使用来自Codex

用户范围：

codex mcp add eco-oracle -- npx -y eco-oracle-mcp

或在 ~/.codex/config.toml:

[[mcp_servers]]
name = "eco-oracle"
command = "npx"
args = ["-y", "eco-oracle-mcp"]

[mcp_servers.env]
ECO_REGISTRY_URL = "https://raw.githubusercontent.com/bbuchsbaum/eco-registry/main/registry.json"
ECO_GITHUB_TOKEN = "${ECO_GITHUB_TOKEN}"

MCP工具

• eco_howto(query, ...)
• eco_symbol(symbol, ...)
• eco_packages(...)
• eco_where_used(symbol, ...)
• eco_refresh()

操作检查表

对于每个包裹：

1. .ecosystem.yml 当前有效。
2. eco-atlas 工作流在上运行 main.
3. 发布标签 eco-atlas 有 atlas-pack.tgz.

对于注册表：

1. 夜间发现工作流程成功。
2. registry.json 自动更新。
3. 新包出现时无需手动编辑。

对于客户：

1. MCP配置指向正确的注册表URL/路径。
2. eco_refresh() 返回预期的包裹/卡片/符号计数。