Echosphere MCP

Echosphere MCP 服务器

一个全面的模型上下文协议（MCP）服务器，提供多种AI辅助工具。这种模块化的服务器架构使得在保持安全性和性能的同时，能够轻松扩展新工具。

特点/特性

文件操作

• 单文件读取通过指定相对路径读取单个文件
• 目录读取读取目录中的所有文件（非递归）
• 文件移动在工作区内将文件从一个位置移动到另一个位置
• 文件重命名在同一目录内重命名文件
• 安全内置保护以抵御目录遍历攻击
• 验证对工作区根目录和文件路径进行输入验证
• 错误处理全面的错误处理，提供清晰的错误信息

内存管理（RAG系统）

• 基于RAG的增强记忆（或：RAG驱动的记忆）利用嵌入进行语义搜索的高级检索增强生成
• 加载内存使用自然语言和向量相似性搜索查询内存
• 节省内存通过自动嵌入生成和智能分块节省内存
• 语义搜索使用AI嵌入技术而非简单的文本匹配来查找相关信息
• 智能分块自动将大内容分割成最佳片段，并设置重叠
• 大型语言模型（LLM）集成使用配置好的AI模型进行嵌入和响应生成

建筑学

• 模块化设计工具被组织成独立的模块，以便于维护
• 可扩展结构易于添加新工具和功能
• 共享公用设施公共功能集中管理以确保一致性
• 类型安全全面支持TypeScript，提供完整的类型定义

安装

1. 克隆或创建项目目录：

   mkdir echosphere-mcp-server
   cd echosphere-mcp-server

1. 安装依赖项：

   npm install

1. 搭建服务器:

   npm run build

使用方法

工具： read_files

从工作区目录中读取一个或多个文件。

参数

参数详情

• workspaceRoot必须是一个指向现有目录的绝对路径，该目录作为您工作区的根目录
• relativePaths从工作区根目录开始的相对文件路径数组

- 字符串数组用于一次性读取多个特定文件 - 对于 文件指定您想要读取的特定文件（或文件）的相对路径 - 对于 目录（或文件夹）指定相对于当前目录的路径，以读取该目录内的所有文件（非递归） - 使用 ["."] 读取工作区根目录中的所有文件 - 至少需要1个文件路径，最多50个以达到最佳性能

示例

读取单个文件：

{
  "workspaceRoot": "/home/user/my-project",
  "relativePaths": ["src/index.js"]
}

读取目录中的所有文件：

{
  "workspaceRoot": "/home/user/my-project", 
  "relativePaths": ["src"]
}

读取工作区根目录下的所有文件：

{
  "workspaceRoot": "/home/user/my-project",
  "relativePaths": ["."]
}

读取多个特定文件：

{
  "workspaceRoot": "/home/user/my-project",
  "relativePaths": ["src/index.js", "package.json", "README.md"]
}

读取多个文件和目录：

{
  "workspaceRoot": "/home/user/my-project",
  "relativePaths": ["src/utils.js", "config", "docs/api.md"]
}

响应格式

单文件响应：

• 返回包含文件路径和大小等元数据的文件内容
• 内容以纯文本形式返回

多文件响应：

• 返回指定目录中所有文件的内容
• 每个文件都清晰地分隔开，文件头显示文件路径和大小
• 无法读取的文件将显示错误信息，而非内容

安全特性

• 路径遍历保护防止使用（某功能/方法）读取工作区根目录之外的文件 ../ 或绝对路径
• 工作区验证确保工作区根目录存在且为目录
• 路径解析所有路径在访问前均经过规范化和验证

错误处理

该工具为常见问题提供了清晰的错误信息：

• 工作区根目录不存在或不是目录
• 文件或目录未找到
• 权限被拒绝
• 路径遍历尝试
• 文件读取错误

工具： move_file

在工作区内部，将文件从一个位置移动到另一个位置。

参数

| 字符串 | 是 | 文件应移动到的相对路径（包括新文件名） |

{
  "workspaceRoot": "/home/user/my-project",
  "sourceRelativePath": "src/old-file.js",
  "targetRelativePath": "src/components/new-file.js"
}

示例 rename_file

工具：

在同一目录内重命名文件。

参数 | 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| workspaceRoot | 中文翻译 |------|----------|-------------| | relativePath | 字符串 | 是 | 工作区根目录的绝对路径 | | newName | 字符串 | 是 | 要重命名的文件的相对路径 |

|

{
  "workspaceRoot": "/home/user/my-project",
  "relativePath": "src/component.js",
  "newName": "new-component.js"
}

| 字符串 | 是 | 文件的新名称（仅文件名，不含路径） | load_memory

示例

工具：

使用具备语义搜索功能的RAG（检索增强生成）技术加载内存。 参数 | 参数 | 类型 | 必填 | 描述 | workspaceRoot |-----------|------|----------|-------------| |（无对应中文翻译，表示表格分隔线）|（无对应中文翻译）|（无对应中文翻译）|（无对应中文翻译）| query | | 字符串 | 是 | 工作区根目录的绝对路径 | maxResults | | 字符串 | 否 | 使用语义相似性在内存中搜索的自然语言查询 | useRAG |

| number | No | 返回的最大相似内存块数量（默认：5） |

|

{
  "workspaceRoot": "/home/user/my-project"
}

| 布尔值 | 否 | 是否使用RAG生成响应（默认：true） |

{
  "workspaceRoot": "/home/user/my-project",
  "query": "How do I configure the database connection?",
  "maxResults": 3,
  "useRAG": true
}

示例

{
  "workspaceRoot": "/home/user/my-project",
  "query": "API endpoints",
  "useRAG": false
}

加载全部内存：

• 使用RAG进行语义查询：无需RAG生成的语义搜索：
• 特点/特性语义搜索
• 利用人工智能嵌入技术来查找上下文相关的记忆片段RAG响应
• 利用检索到的记忆上下文生成清晰、智能的回复向量相似度
• 即使精确关键词不匹配，也能找到相似内容可配置的结果
• 控制检索相似数据块的数量清洁输出

自动去除AI回复中的Markdown格式 save_memory

自动创建

如果内存系统不存在，则会自动初始化

工具： 通过自动嵌入生成和智能分块技术节省内存。 参数 workspaceRoot | 参数 | 类型 | 必填 | 描述 | |-----------|------|----------|-------------| content | 中文翻译 | 中文 | 中文 | 中文 | | append | 字符串 | 是 | 工作区根目录的绝对路径 | | metadata | 字符串 | 是 | 要保存的内存内容（自动分块并嵌入） | | tags | boolean | 否 | 是否将内容追加到现有内存中或替换它（默认：false） |

|

| 对象 | 否 | 可选的与内存相关联的元数据 |

{
  "workspaceRoot": "/home/user/my-project",
  "content": "The database connection uses PostgreSQL on port 5432. The connection string format is postgresql://user:pass@localhost:5432/dbname. Always use connection pooling for better performance.",
  "metadata": {"source": "documentation", "type": "configuration"},
  "tags": ["database", "postgresql", "configuration"]
}

|

{
  "workspaceRoot": "/home/user/my-project",
  "content": "API rate limiting is set to 1000 requests per hour per user. Use exponential backoff for retries.",
  "append": true,
  "tags": ["api", "rate-limiting"]
}

| 字符串数组 | 否 | 可选标签，用于对内存进行分类 |

• 示例使用嵌入保存新记忆：
• 追加到现有内存：特点/特性
• 自动嵌入为语义搜索生成向量嵌入
• 智能分块将大段内容按句子边界拆分成最佳片段
• 块重叠在数据块之间保持智能重叠的上下文连贯性
• 元数据支持在内存中存储额外的结构化信息

标签系统

对记忆进行分类以更好地组织

统计 .env 返回关于内存存储的详细信息

# AI Configuration
AI_BASE_URL=https://ai.echosphere.cfd/v1
AI_API_KEY=your-api-key-here
AI_MODEL=mistral-small-latest
AI_EMBEDDING_MODEL=mistral-embed

# Search API (optional)
SEARXNG_URL=https://search.echosphere.cfd

配置

• 环境变量创建一个
• 在项目根目录下创建一个文件，配置如下：环境变量详情
• AI基础URLAI API 端点的基础 URL
• AI_API_KEY您的AI服务API密钥
• AI模型用于RAG（检索增强生成）响应生成的LLM（大型语言模型）

AI嵌入模型

用于语义搜索的嵌入模型

{
  "mcpServers": {
    "echosphere": {
      "command": "node",
      "args": ["/absolute/path/to/your/dist/index.js"]
    }
  }
}

SEARXNG_URL（注：此翻译保留了原术语的形式，若需具体解释，可译为“SEARXNG搜索引擎URL”或根据上下文具体说明其含义） /absolute/path/to/your 可选的搜索API端点

克劳德桌面配置

1. 在您的Claude桌面配置文件中添加以下内容：
2. 替换 npm run build
3. 使用您构建的服务器的实际路径。

环境设置

确保已安装 Node.js v16.0.0 或更高版本

echosphere-mcp-server/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── tools/            # Tool implementations
│   │   ├── index.ts      # Tool registry
│   │   ├── file-reader.ts # File reading tool
│   │   ├── move-file.ts  # File moving tool
│   │   ├── rename-file.ts # File renaming tool
│   │   ├── load-memory.ts # Memory loading tool with RAG
│   │   └── save-memory.ts # Memory saving tool with embeddings
│   └── shared/           # Shared utilities
│       ├── types.ts      # Common type definitions
│       ├── validation.ts # Input validation utilities
│       └── file-operations.ts # File operation utilities
├── dist/                 # Built JavaScript files (after npm run build)
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── mcp.json             # MCP client configuration
└── README.md             # This file

构建项目：

• npm run build配置您的MCP客户端以使用内置服务器
• npm run watch发展
• npm start项目结构

可用脚本

构建TypeScript项目

1. 监控变化并自动重建 运行已构建的服务器（需先进行构建） src/tools/ 添加新工具 my-new-tool.ts要在Echosphere MCP服务器上添加一个新工具：
2. 创建一个工具文件 在里面

   import { z } from "zod";
   import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

   export const myToolSchema = {
     param1: z.string().describe("Description of param1"),
     param2: z.number().describe("Description of param2")
   };

   export async function myToolHandler({ param1, param2 }: z.infer) {
     // Tool implementation
     return {
       content: [{ type: "text", text: "Tool result" }]
     };
   }

   export function registerMyTool(server: McpServer): void {
     server.tool("my_tool", myToolSchema, myToolHandler);
   }

1. （例如。， ) src/tools/index.ts实施该工具

   import { registerMyTool } from "./my-new-tool.js";

   export function registerAllTools(server: McpServer): void {
     registerFileReaderTool(server);
     registerMyTool(server); // Add this line
   }

1. 遵循以下模式： 注册该工具

在

• validateAndNormalizePath():
• readSingleFile()更新可用工具数组
• readDirectoryFiles()用于记录/文件编制
• getPathType()主要功能

验证文件路径并防止目录遍历攻击

1. 读取单个文件并处理错误读取目录中的所有文件
2. 判断路径是文件、目录还是不存在安全考量
3. 工作区边界所有文件访问均限制在指定的工作区根目录内
4. 路径验证输入路径经过验证和规范化处理，以防止安全问题

错误清理

错误信息不会泄露敏感的文件系统信息

1. 无写入操作

- 这台服务器仅读取文件，从不修改它们 workspace_root 故障排除

1. 常见问题

- “工作区根目录不存在” - 确保 relative_path 参数包含一个有效、指向现有目录的绝对路径 ../ “路径位于工作区根目录之外”

1. 这是一个防止目录遍历的安全功能

- 确保你的

1. 不使用

- 逃离工作区 npm install “权限被拒绝” - 确保服务器对您尝试访问的文件具有读取权限

构建错误

跑