项目简介

FinClip Agent 是一个基于 Model Context Protocol (MCP) 和 actgent 框架开发的智能对话代理后端。它设计轻巧，易于部署，旨在帮助开发者快速将智能对话能力嵌入到网页、小程序或其他应用中。项目支持通过配置对接大语言模型（LLM），并通过 MCP 调用外部服务（如知识库检索、功能调用），为 LLM 提供丰富的上下文和功能。

主要功能点

快速部署: 无需复杂安装，通过简单的配置和命令即可运行。
嵌入式UI: 提供可轻松集成到任何网页的聊天小组件。
知识库集成 (RAG): 可通过 MCP 调用外部知识库服务增强回复。
外部工具集成: 可通过 MCP 调用外部工具（如文件系统访问）。
多协议支持: 支持 HTTP, Server-Sent Events (SSE) 和 WebSocket 等协议与前端通信。
会话管理: 内建会话状态管理。
可定制Agent: 通过 markdown 文件定义 Agent 的性格、目标和能力。
可观测性: 可选支持通过 NATS 监控对话数据。

安装步骤

确保已安装 Bun 运行时。

创建一个新的项目目录，并在其中创建 '.agent.env' 文件，配置 LLM API Key 和服务器端口等信息。例如：

LLM_API_KEY=your-openai-or-compatible-key
LLM_PROVIDER_URL=https://your-llm-provider-endpoint
LLM_MODEL=your-model-name
AGENT_HOST=0.0.0.0
AGENT_HTTP_PORT=5678
AGENT_STREAM_PORT=5679
AGENT_ENABLE_STREAMING=true

（可选）创建 'brain.md' 文件定义 Agent 的行为（如 README 中的示例）。

在项目目录中运行以下命令启动 Agent：

bunx @finogeek/cxagent

或者，使用 '--inspect' 参数启动带配置检查UI的 Agent：

bunx @finogeek/cxagent --inspect

服务器配置 (MCP 工具集成)

FinClip Agent 可以作为 MCP 主机，通过调用其他 MCP 服务器来扩展自身功能，例如进行知识库检索（RAG）或访问文件系统。这些外部 MCP 服务器通过 JSON-RPC 协议与 FinClip Agent 通信。

要配置这些外部 MCP 工具，您需要在项目目录下创建一个 'conf' 文件夹，并在其中放置 JSON 配置文件（例如 'mcp_config.json' 或 'preproc-mcp.json'）。

MCP 工具配置 ('conf/mcp_config.json'): 用于配置由 LLM 工具调用触发的 MCP 服务器。

{
    "mcpServers": {
      "filesystem": { // 服务器名称，由LLM工具调用指定
        "command": "npx", // 启动该MCP服务器的命令
        "args": [ // 传递给命令的参数
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/path/to/directory1", // 文件系统服务器需要访问的目录
          "/path/to/directory2"
        ]
      }
      // 可以在这里配置其他MCP服务器
    }
}

MCP 知识库预处理器配置 ('conf/preproc-mcp.json'): 用于配置在发送给 LLM 之前对用户查询进行预处理的 MCP 服务器（例如基于 RAG 的知识库检索）。

{
    "mcpServers": {
      "some-rag-server": { // 服务器名称，通常固定为用于预处理的名称
        "command": "/path/to/your/kb-mcp-server", // 启动知识库MCP服务器的命令
        "args": [ // 传递给知识库MCP服务器的参数
          "/path/to/some-knowledgebase/some-data", // 知识库数据路径
          "--some-param", "some-value" // 其他参数
        ]
      }
      // 可以在这里配置其他用于预处理的MCP服务器
    }
}

基本使用方法

服务器启动后，您可以通过 Inspector UI (如果使用 '--inspect' 启动) 在网页上与 Agent 交互。
您也可以将 Agent 提供的嵌入式脚本 ('finclip-chat-embed.iife.js') 集成到您的网页中，以显示聊天小组件。具体集成代码示例请参考项目 README 的 "Embed the Chatbot in a Website" 或 "Embedding the Chat Widget" 部分。
对于小程序或其他客户端，您需要实现相应的逻辑来通过 HTTP 或 WebSocket 与 Agent 配置的 API 端口进行通信（POST 请求到 '/chat' 发送消息，连接 '/session/{sessionId}' 获取 SSE 或 WebSocket 流）。

关键词

信息