Aztec MCP Server

Aztec MCP服务器

一个MCP（模型上下文协议）服务器，通过克隆的存储库提供对Aztec文档、示例和源代码的本地访问。可选增强 语义搜索 当配置API密钥时，通过完整的阿兹特克知识库。

特性

• 版本支持：克隆特定的阿兹特克释放标签（例如。， v4.2.0)
• 本地存储库克隆：通过稀疏校验自动克隆Aztec存储库以提高效率
• 快速代码搜索：使用ripgrep搜索Noir合约和TypeScript文件（带回退）
• 文档搜索在当地搜索阿兹特克文献；使用API键，在整个语料库中进行语义向量搜索（框架文档、示例、Noir stdlib、TypeScript SDK、协议电路）
• 错误查找：静态目录（Solidity/circircuit/TX/AVM错误）加上配置API密钥时无法识别错误的可选语义回退
• 示例发现：列出并阅读阿兹特克合同示例
• 版本同步门：使用托管语义后端时，服务器会检测到本地克隆标记和索引语料库之间的不匹配，并拒绝跨版本查询，除非明确覆盖

API密钥（可选，推荐）

MCP服务器以两种模式运行：

获取钥匙

1. 加入阿兹特克人/黑人部落：
2. 跑 /mcp-key 在任何渠道-机器人DM会为您提供个人API密钥（UUID）。
3. 将密钥粘贴到MCP客户端配置中 env.API_KEY （参见 配置).

密钥是免费的、持久的（重新运行 /mcp-key 返回相同的密钥），并可通过以下方式撤销 /forget-me.

安装

使用npx（推荐）

npx -y @aztec/mcp-server@latest

始终固定 @latest. npx积极缓存包——没有 @latest，您最终可能会无限期地运行旧版本。这 @latest 标签强制npx在每次运行时检查注册表中的当前版本。如果服务器在npm上检测到较新版本，它还会在启动时自我报告升级可用警告（请参阅 aztec_status 输出）。

全局安装

npm install -g @aztec/mcp-server@latest
aztec-mcp

稍后更新： npm install -g @aztec/mcp-server@latest （或者仅仅依靠 npx -y @aztec/mcp-server@latest 表单，它总是获取当前值）。

配置

Claude代码插件

添加到您的 .mcp.json.最小配置只是命令；添加 env.API_KEY 以启用语义搜索。

{
  "mcpServers": {
    "aztec-mcp": {
      "command": "npx",
      "args": ["-y", "@aztec/mcp-server@latest"],
      "env": {
        "API_KEY": ""
      }
    }
  }
}

可用工具

aztec_sync_repos

在本地克隆或更新Aztec存储库。 先运行这个 以启用其他工具。

Clones:
- aztec-packages (docs, aztec-nr, noir-contracts) - sparse checkout
- aztec-examples (full)
- aztec-starter (full)

参数：

• version （string）：要克隆的Aztec版本标签（例如。， v4.2.0).默认为支持的最新版本。
• force （boolean）：即使存在repos，也强制重新克隆
• repos （string\[\]）：要同步的特定存储库

示例-克隆特定版本：

aztec_sync_repos({ version: "v4.2.0" })

aztec_status

检查克隆存储库的状态。

aztec_search_code

搜索Aztec合同代码和源文件。支持正则表达式模式。

参数：

• query （字符串，必填）：搜索查询（支持正则表达式）
• filePattern （string）：文件glob模式（默认值： *.nr)
• repo （string）：要搜索的特定仓库
• maxResults （数字）：最大结果（默认值：30）

例子：

aztec_search_code({ query: "PrivateSet", filePattern: "*.nr" })

aztec_search_docs

搜索阿兹特克文档。默认情况下为本地ripgrep；语义向量搜索 API_KEY 已设置。

参数：

• query （字符串，必填）：文档搜索查询
• section （string）：文档部分，仅适用于本地搜索（教程、概念、开发人员、参考）
• maxResults （数字）：最大结果数（默认：20个局部；5个语义，最大20个）
• chunks （数字，仅语义）：结果块的数量（1-20）。如果省略， maxResults 使用。
• useLocalFallback （布尔值，仅语义）：如果语义后端失败，则回退到本地ripgrep。默认 false 因此后端错误显而易见。
• allowVersionMismatch （布尔值，仅语义）：覆盖版本同步门。默认 false当你在附近时，大门拒绝搜查 aztec-packages clone标签与后端索引的语料库版本不同。

aztec_list_examples

列出可用的阿兹特克合同示例。

参数：

• category （string）：按类别筛选（代币、nft、defi、托管、众筹）

aztec_read_example

阅读阿兹特克合同示例的源代码。

参数：

• name （字符串，必填）：合同名称示例

aztec_read_file

从克隆的存储库中读取任何文件。

参数：

• path （字符串，必填）：相对于repos目录的文件路径

aztec_lookup_error

通过消息、错误代码或十六进制签名诊断任何Aztec错误。从静态目录中返回根本原因和建议修复，包括Solidity错误、TX验证错误、电路代码、AVM错误和操作员常见问题。随着 API_KEY 当静态目录没有命中时，set会回退到语义文档搜索。

参数：

• query （字符串，必填）：错误消息、数字代码（例如。， 2002)或十六进制签名（例如。， 0xa5b2ba17)
• category （字符串）：筛选器(contract, circuit, tx-validation, l1, avm, sequencer, operator, general)
• maxResults （数字）：默认值10
• allowVersionMismatch （布尔值，仅限语义）：覆盖语义回退的版本同步门。当静态目录已匹配时，此功能无效。

配置选项

存储位置

存储库被克隆到 ~/.aztec-mcp/repos/ 默认情况下。

用覆盖 AZTEC_MCP_REPOS_DIR 环境变量：

{
  "mcpServers": {
    "aztec-mcp": {
      "command": "npx",
      "args": ["-y", "@aztec/mcp-server@latest"],
      "env": {
        "AZTEC_MCP_REPOS_DIR": "/custom/path"
      }
    }
  }
}

默认Aztec版本

使用以下命令设置默认的Aztec版本 AZTEC_DEFAULT_VERSION 环境变量：

{
  "mcpServers": {
    "aztec-mcp": {
      "command": "npx",
      "args": ["-y", "@aztec/mcp-server@latest"],
      "env": {
        "AZTEC_DEFAULT_VERSION": "v3.0.0-devnet.6-plugin.1"
      }
    }
  }
}

发展

# Clone the repo
git clone https://github.com/aztecprotocol/mcp-server
cd mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js

需求

• Node.js 18+
• Git
• ripgrep（可选，用于更快的搜索）

克隆存储库

许可证

麻省理工学院