构建AgentQL MCP服务器 | zh-CN

AgentQL 提供了一种新颖的网页抓取方法，使用户能够通过精确定义所需信息的结构，从具有非结构化格式的网站提取数据。即使从具有动态内容或频繁更改布局的网站，这也能实现一致且结构化的数据检索。

在本综合指南中，我们将逐步完成在 Claude Desktop 中实现 AgentQL MCP 服务器的过程。我们将利用 Claude 的集成可视化工具来探索提取的数据。我们的具体示例将涉及抓取 Amazon 搜索结果页面上的 AI books，提取关键详细信息，例如价格、评分和评论数。

步骤 1：设置依赖项

在深入实施之前，我们需要确保已安装并配置了所有必要的依赖项。这包括设置 Node.js、Claude Desktop 并获取 AgentQL API 密钥。

Node.js

Node.js 是一个 JavaScript 运行时环境，允许我们在 Web 浏览器之外执行 JavaScript 代码。需要使用 npx 运行 AgentQL 服务器，npx 是 Node.js 捆绑在一起的包运行器。

要安装 Node.js，请按照下列步骤操作：

访问 Node.js 官方网站：nodejs.org。
下载最新 LTS（长期支持）版本的 Node.js。
运行安装程序。
接受许可协议并完成安装向导。
将所有设置保留为默认设置并完成安装。

安装完成后，通过打开终端或命令提示符并运行以下命令，验证 Node.js 和 npm (Node Package Manager) 是否已正确安装：

1 2	node -v npm -v

如果这些命令返回版本号，则表示 Node.js 和 npm 已成功安装。

Claude Desktop

Claude Desktop 是 Anthropic 提供的用于与 Claude 模型交互的桌面应用程序。我们将使用它来运行 AgentQL MCP 服务器并可视化提取的数据。

要安装 Claude Desktop，请按照下列步骤操作：

访问 Anthropic 官方网站或 Claude Desktop 的下载页面。
下载适合您操作系统的 Claude Desktop 版本。
运行安装程序并按照屏幕上的说明进行操作。
安装完成后，启动 Claude Desktop。

启动 Claude Desktop 后，您可能需要登录或创建一个帐户（如果尚未这样做）。确保您已配置 Claude Desktop 以与您的 AgentQL 服务器通信。

AgentQL API 密钥

要使用 AgentQL，您需要一个 API 密钥。您可以从 AgentQL 网站获取 API 密钥。获取 API 密钥后，将其保存在安全的地方，因为稍后需要它来配置 AgentQL MCP 服务器。

步骤 2：创建 AgentQL MCP 服务器

现在我们已经设置了必要的依赖项，我们可以创建 AgentQL MCP 服务器了。

创建项目目录

首先，创建一个新的目录来存放我们的 AgentQL MCP 服务器文件：

1 2	mkdir agentql-mcp-server cd agentql-mcp-server

初始化 Node.js 项目

接下来，初始化一个新的 Node.js 项目：

1	npm init -y

这将在您的项目目录中创建一个 package.json 文件。

安装依赖项

我们需要安装几个依赖项来创建 AgentQL MCP 服务器：

agentql: AgentQL 库。
express: 用于创建 Web 服务器。
cors: 用于启用跨域资源共享 (CORS)。
dotenv: 用于从 .env 文件加载环境变量。

使用以下命令安装这些依赖项：

1	npm install agentql express cors dotenv

创建服务器文件

创建一个名为 server.js 的文件，并将以下代码添加到其中：

const express = require('express');
const cors = require('cors');
const { AgentQL } = require('agentql');
require('dotenv').config();

const app = express();
const port = process.env.PORT || 3000;

app.use(cors());
app.use(express.json());

const agentQL = new AgentQL({ apiKey: process.env.AGENTQL_API_KEY });

app.post('/query', async (req, res) => {
  try {
    const { query, url } = req.body;
    const results = await agentQL.query({ query, url });
    res.json(results);
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: error.message });
  }
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

此代码创建一个 Express 服务器，该服务器公开一个 /query 路由。此路由接受一个包含 query (AgentQL 查询) 和 url (要抓取的 URL) 的 JSON 有效负载。然后，它使用 AgentQL 库执行查询并返回结果。

创建 .env 文件

创建一个名为 .env 的文件，并将您的 AgentQL API 密钥添加到其中：

1	AGENTQL_API_KEY=YOUR_AGENTQL_API_KEY

将 YOUR_AGENTQL_API_KEY 替换为您的实际 AgentQL API 密钥。

注意： 将 .env 文件添加到您的 .gitignore 文件，以防止将您的 API 密钥提交到版本控制系统。

运行服务器

使用以下命令运行服务器：

1	node server.js

如果一切顺利，您应该会在控制台中看到 Server listening on port 3000 消息。

步骤 3：在 Claude Desktop 中使用 AgentQL MCP 服务器

现在我们的 AgentQL MCP 服务器正在运行，我们可以从 Claude Desktop 中使用它。

创建一个 Claude 工作区

打开 Claude Desktop 并创建一个新的工作区。

添加一个代码块

向工作区添加一个代码块。

使用 JavaScript 代码向 MCP 服务器发送请求

在代码块中，添加以下 JavaScript 代码：

async function queryAgentQL(query, url) {
  const response = await fetch('http://localhost:3000/query', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, url }),
  });

  const data = await response.json();
  return data;
}

// 示例用法
const query = `
  product:
    xpath: //div[@data-component-type='s-search-result']
    properties:
      title:
        xpath: .//h2/a/span
      price:
        xpath: .//span[@class='a-price']/span[@class='a-offscreen']
      rating:
        xpath: .//i[@class='a-icon a-icon-star-small a-star-small-4-5 aok-align-top']/span
      reviewCount:
        xpath: .//a[@class='a-link-normal s-underline-text s-underline-link-text s-link-style']/span
`;
const url = 'https://www.amazon.com/s?k=ai+books';

queryAgentQL(query, url)
  .then(results => {
    console.log(results);
    // 在 Claude 中显示结果
    Claude.text(JSON.stringify(results, null, 2));
  })
  .catch(error => {
    console.error(error);
    Claude.text(`Error: ${error.message}`);
  });

此代码定义了一个 queryAgentQL 函数，该函数向 AgentQL MCP 服务器发送 POST 请求。该函数接受 AgentQL 查询和 URL 作为参数，并返回服务器返回的结果。

示例用法部分定义了一个 AgentQL 查询，该查询从 Amazon 搜索结果页面中提取 AI 书籍的标题、价格、评分和评论数。然后，它调用 queryAgentQL 函数并打印结果。最后，使用 Claude.text() 函数将结果显示在 Claude Desktop 中。

运行代码块

运行代码块。您应该会在 Claude Desktop 中看到提取的数据。

步骤 4：可视化提取的数据

Claude Desktop 提供了多种可视化提取数据的方式。例如，您可以使用表格、图表或其他可视化效果来显示数据。

使用表格显示数据

要使用表格显示数据，请将以下代码添加到代码块中：

async function queryAgentQL(query, url) {
  const response = await fetch('http://localhost:3000/query', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, url }),
  });

  const data = await response.json();
  return data;
}

// 示例用法
const query = `
  product:
    xpath: //div[@data-component-type='s-search-result']
    properties:
      title:
        xpath: .//h2/a/span
      price:
        xpath: .//span[@class='a-price']/span[@class='a-offscreen']
      rating:
        xpath: .//i[@class='a-icon a-icon-star-small a-star-small-4-5 aok-align-top']/span
      reviewCount:
        xpath: .//a[@class='a-link-normal s-underline-text s-underline-link-text s-link-style']/span
`;
const url = 'https://www.amazon.com/s?k=ai+books';

queryAgentQL(query, url)
  .then(results => {
    console.log(results);
    // 在 Claude 中显示表格
    Claude.table(results);
  })
  .catch(error => {
    console.error(error);
    Claude.text(`Error: ${error.message}`);
  });

此代码使用 Claude.table() 函数在 Claude Desktop 中显示提取的数据。

探索其他可视化效果

Claude Desktop 提供了多种其他可视化效果，您可以使用它们来显示提取的数据。尝试使用不同的可视化效果来找到最适合您需求的可视化效果。

结论

在本指南中，我们学习了如何在 Claude Desktop 中实现 AgentQL MCP 服务器。我们还学习了如何使用 Claude Desktop 可视化提取的数据。通过使用 AgentQL 和 Claude Desktop，您可以轻松地从网站提取数据并可视化数据。

此设置使我们能够高效地从网页抓取数据，并且 Claude Desktop 提供了一个强大的环境来探索和可视化这些数据。记住总是检查网站的 robots.txt 文件，并遵守其抓取策略以确保符合道德规范。此外，请考虑处理抓取请求的速率限制和适当的错误，以避免出现问题。通过这些实践，您可以成功地使用 AgentQL 构建和部署数据抓取解决方案，并将其集成到 Claude Desktop 环境中。

更新于 2025-05-07

# AI # Claude # Agent