内容
# 容器-MCP
[](https://opensource.org/licenses/Apache-2.0)
一个安全的、基于容器的MCP(模型上下文协议)实现,用于代表大型语言模型执行工具。
## 概述
容器-MCP提供了一个沙盒环境,用于安全地执行代码、运行命令、访问文件和执行大型语言模型请求的操作。它实现了MCP协议,将这些功能以工具的形式暴露出来,可以被AI系统在安全的情况下发现和调用。
该架构使用领域特定管理器模式,具有多层安全机制,确保工具在隔离的环境中执行,并具有适当的限制,保护主机系统免受潜在的恶意操作。
## 主要功能
- **多层安全**
- 使用Podman/Docker的容器隔离
- AppArmor配置文件,用于限制访问
- Firejail沙盒,提供额外的隔离
- 资源限制(CPU、内存、执行时间)
- 路径遍历预防
- 允许扩展限制
- **MCP协议实现**
- 标准化工具发现和执行
- 资源管理
- 异步执行支持
- **领域特定管理器**
- `BashManager`:安全的命令执行
- `PythonManager`:沙盒Python代码执行
- `FileManager`:安全的文件操作
- `WebManager`:安全的网页浏览和抓取
- `KnowledgeBaseManager`:具有语义搜索的结构化文档存储
- `ListManager`:有组织的列表和集合管理
- `MarketManager`:通过Yahoo Finance获取股票和加密货币数据
- `RssManager`:RSS和Atom饲料获取
- **可配置环境**
- 通过环境变量进行广泛配置
- 自定义环境支持
- 开发和生产模式
## 可用工具
### 系统操作
#### `system_run_command`
在安全的沙盒环境中执行bash命令。
- **参数**:
- `command`(字符串,必填):要执行的bash命令
- `working_dir`(字符串,可选):工作目录(在沙盒中忽略)
- **返回**:
- `stdout`(字符串):命令的标准输出
- `stderr`(字符串):命令的标准错误
- `exit_code`(整数):命令的退出代码
- `success`(布尔值):命令是否成功完成
```json
{
"stdout": "file1.txt\nfile2.txt\n",
"stderr": "",
"exit_code": 0,
"success": true
}
```
#### `system_run_python`
在安全的沙盒环境中执行Python代码。
- **参数**:
- `code`(字符串,必填):要执行的Python代码
- `working_dir`(字符串,可选):工作目录(在沙盒中忽略)
- **返回**:
- `output`(字符串):代码的打印输出
- `error`(字符串):代码的错误输出
- `result`(任意值):可选的返回值(如果代码设置了 `_` 变量)
- `success`(布尔值):代码是否成功执行
```json
{
"output": "Hello, world!\n",
"error": "",
"result": 42,
"success": true
}
```
#### `system_env_var`
获取环境变量值。
- **参数**:
- `var_name`(字符串,可选):要检索的特定变量
- **返回**:
- `variables`(对象):环境变量字典
- `requested_var`(字符串):请求的变量的值(如果提供了 `var_name`)
```json
{
"variables": {
"MCP_PORT": "8000",
"SANDBOX_ROOT": "/app/sandbox"
},
"requested_var": "8000"
}
```
#### `health_check`
获取服务器健康状态和系统信息。
- **参数**:无
- **返回**:
- `status`(字符串):服务器健康状态
- `timestamp`(字符串):当前ISO时间戳
- `server`(对象):服务器详细信息(名称、主机、端口、平台、Python版本)
- `system`(对象):系统指标(CPU百分比、内存百分比、磁盘百分比)
- `managers`(对象):每个管理器的状态(启用/禁用)
```json
{
"status": "healthy",
"timestamp": "2024-01-15T10:30:00.000Z",
"server": {
"name": "Container-MCP",
"host": "127.0.0.1",
"port": 9001,
"platform": "linux",
"python_version": "3.12.0"
},
"system": {
"cpu_percent": 12.5,
"memory_percent": 45.2,
"disk_percent": 67.8
},
"managers": {
"bash": "enabled",
"python": "enabled",
"file": "enabled",
"web": "enabled",
"kb": "enabled",
"list": "enabled",
"market": "enabled",
"rss": "enabled"
}
}
```
### 文件操作
#### `fs_read`
安全地读取文件内容。
- **参数**:
- `path`(字符串,必填):文件路径(相对于沙盒根目录)
- `encoding`(字符串,可选):文件编码(默认:"utf-8")
- **返回**:
- `content`(字符串):文件内容
- `size`(整数):文件大小(字节)
- `modified`(浮点数):最后修改时间戳
- `success`(布尔值):读取是否成功
```json
{
"content": "This is the content of the file.",
"size": 31,
"modified": 1673452800.0,
"success": true
}
```
#### `fs_write`
安全地将内容写入文件。
- **参数**:
- `path`(字符串,必填):文件路径(相对于沙盒根目录)
- `content`(字符串,必填):要写入的内容
- `encoding`(字符串,可选):文件编码(默认:"utf-8")
- **返回**:
- `success`(布尔值):写入是否成功
- `path`(字符串):写入的文件路径
```json
{
"success": true,
"path": "data/myfile.txt"
}
```
#### `fs_list`
安全地列出目录内容。
- **参数**:
- `path`(字符串,可选):目录路径(默认:"/")
- `pattern`(字符串,可选):通配模式,用于筛选文件
- `recursive`(布尔值,可选):是否递归列出(默认:true)
- **返回**:
- `entries`(数组):目录条目列表,包含元数据
- `path`(字符串):列出的目录路径
- `success`(布尔值):列出是否成功
```json
{
"entries": [
{
"name": "file1.txt",
"path": "file1.txt",
"is_directory": false,
"size": 1024,
"modified": 1673452800.0
},
{
"name": "data",
"path": "data",
"is_directory": true,
"size": null,
"modified": 1673452500.0
}
],
"path": "/",
"success": true
}
```
#### `fs_delete`
安全地删除文件。
- **参数**:
- `path`(字符串,必填):要删除的文件路径
- **返回**:
- `success`(布尔值):删除是否成功
- `path`(字符串):删除的文件路径
```json
{
"success": true,
"path": "temp/old_file.txt"
}
```
#### `fs_move`
安全地移动或重命名文件。
- **参数**:
- `source_path`(字符串,必填):源文件路径
- `destination_path`(字符串,必填):目标文件路径
- **返回**:
- `success`(布尔值):移动是否成功
- `source_path`(字符串):原始文件路径
- `destination_path`(字符串):新文件路径
```json
{
"success": true,
"source_path": "data/old_name.txt",
"destination_path": "data/new_name.txt"
}
```
#### `fs_apply_diff`
将统一的diff补丁应用于沙盒文件系统中的文件。
- **参数**:
- `path`(字符串,必填):要修补的文件路径(相对于沙盒根目录)
- `diff`(字符串,必填):要应用的统一diff内容
- **返回**:
- `success`(布尔值):补丁是否成功应用
- `path`(字符串):修补的文件路径
- `lines_applied`(整数):更改的行数
- `new_size`(整数):新文件大小(字节)
- `error`(字符串):如果补丁失败,返回错误消息
```json
{
"success": true,
"path": "src/main.py",
"lines_applied": 5,
"new_size": 1248,
"error": null
}
```
### 网络操作
#### `web_search`
使用搜索引擎查找网络信息。
- **参数**:
- `query`(字符串,必填):要搜索的查询
- **返回**:
- `results`(数组):搜索结果列表
- `query`(字符串):原始查询
```json
{
"results": [
{
"title": "Search Result Title",
"url": "https://example.com/page1",
"snippet": "Text snippet from the search result..."
}
],
"query": "example search query"
}
```
#### `web_scrape`
抓取特定URL并返回内容。
- **参数**:
- `url`(字符串,必填):要抓取的URL
- `selector`(字符串,可选):CSS选择器,用于定位特定内容
- `output_format`(字符串,可选):使用`"markdown"`返回Markdown(保留链接)。默认为纯文本。
- **返回**:
- `content`(字符串):抓取的内容
- `url`(字符串):抓取的URL
- `title`(字符串):页面标题
- `success`(布尔值):抓取是否成功
- `error`(字符串):如果抓取失败,返回错误消息
```json
{
"content": "This is the content of the web page...",
"url": "https://example.com/page",
"title": "Example Page",
"success": true,
"error": null
}
```
Markdown输出示例:
```json
{
"content": "This is a [link](https://example.com) in Markdown...",
"url": "https://example.com/page",
"title": "Example Page",
"success": true,
"error": null
}
```
#### `web_browse`
使用Playwright交互式浏览网站。
注意:`web_browse`需要Playwright浏览器二进制文件。在容器外部,使用`python -m playwright install chromium`(或`playwright install`)安装它们。
- **参数**:
- `url`(字符串,必填):浏览会话的起始URL
- **返回**:
- `content`(字符串):页面HTML内容
- `url`(字符串):任何重定向后的最终URL
- `title`(字符串):页面标题
- `success`(布尔值):浏览是否成功
- `error`(字符串):如果浏览失败,返回错误消息
```json
{
"content": "<!DOCTYPE html><html>...</html>",
"url": "https://example.com/after_redirect",
"title": "Example Page",
"success": true,
"error": null
}
```
### 知识库操作
知识库系统提供具有语义搜索能力的结构化文档存储、RDF样式的关系和元数据管理。文档在层次命名空间结构中组织,并支持首选项(任意RDF三元组)和引用(文档之间的链接)。
#### 文档URI格式
知识库文档使用结构化的URI格式:`kb://namespace/collection[/subcollection]*/name`
- **namespace**:顶级组织单位(例如,“projects”,“research”)
- **collection**:命名空间内的主类别(例如,“documentation”,“notes”)
- **subcollection**:可选的嵌套类别(例如,“api”,“tutorials”)
- **name**:文档标识符(例如,“getting-started”,“user-guide”)
示例:
- `kb://projects/docs/api-reference`
- `kb://research/papers/machine-learning/transformers`
- `kb://personal/notes/meeting-2024-01-15`
#### `kb_create_document`
在知识库中创建新文档,带有可选的元数据和内容。
- **参数**:
- `uri`(字符串,必填):文档URI,格式为"kb://namespace/collection[/subcollection]*/name"
- `metadata`(对象,可选):文档元数据(默认:{})
- `content`(字符串,可选):文档内容(允许一步创建和写入)
- **返回**:
- 带有创建详细信息的完整文档索引对象
- **注意**:您可以通过提供`content`参数一次性创建包含内容的文件,也可以通过先创建然后使用`kb_write_content`添加内容来分两步创建。
```json
{
"namespace": "projects",
"collection": "docs",
"name": "api-reference",
"type": "document",
"subtype": "text",
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z",
"content_type": "text/plain",
"chunked": false,
"fragments": {},
"preferences": [],
"references": [],
"referenced_by": [],
"indices": [],
"metadata": {"author": "John Doe", "version": "1.0"}
}
```
#### `kb_write_content`
将内容写入知识库中现有的文档。
- **参数**:
- `uri`(字符串,必填):文档URI
- `content`(字符串,必填):文档内容
- `force`(布尔值,可选):是否覆盖现有内容(默认:false)
- **返回**:
- 完整的更新文档索引对象
- **注意**:必须先使用`kb_create_document`创建文档。
```json
{
"namespace": "projects",
"collection": "docs",
"name": "api-reference",
"type": "document",
"subtype": "text",
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:35:00.000Z",
"content_type": "text/plain",
"chunked": false,
"fragments": {},
"preferences": [],
"references": [],
"referenced_by": [],
"indices": [],
"metadata": {"author": "John Doe", "version": "1.0"}
}
```
#### `kb_read`
从知识库中读取文档数据。调用时不带`uri`,列出所有文档(取代单独的列出操作的需求)。
- **参数**:
- `uri`(字符串,可选):文档URI。如果省略,列出所有文档。
- `recursive`(布尔值,可选):是否递归列出(默认:true)
- `include_content`(布尔值,可选):是否包含文档内容(默认:false)
- `include_index`(布尔值,可选):是否包含文档元数据(默认:false)
- **返回**:
- 根据请求组件的文档数据。操作模式有三种:
- **列表模式**:当省略`uri`时,返回文档URI列表
- **批量读取模式**:当`uri`是部分路径(命名空间或集合)时,返回多个文档
- **读取模式**:当`uri`是完整文档路径时,返回单个文档
**读取单个文档:**
```json
{
"status": "success",
"uri": "kb://projects/docs/api-reference",
"content": "This is the API reference content...",
"index": {
"namespace": "projects",
"collection": "docs",
"name": "api-reference",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {"author": "John Doe"}
}
}
```
**列出所有文档(无uri):**
```json
{
"mode": "list",
"documents": [
"kb://projects/docs/api-reference",
"kb://projects/docs/user-guide",
"kb://research/papers/transformers"
],
"count": 3
}
```
#### `kb_update_triples`
管理文档的RDF三元组(首选项、引用和元数据)。此工具还通过`triple_type="metadata"`处理元数据更新,取代单独的元数据更新操作的需求。
- **参数**:
- `action`(字符串,必填):要执行的操作("add" 或 "remove")
- `triple_type`(字符串,必填):三元组类型("preference", "reference",或 "metadata")
- `uri`(字符串,必填):源文档URI
- `predicate`(字符串,必填):三元组的谓词
- `object`(字符串,可选):三元组的对象(用于首选项和元数据)
- `ref_uri`(字符串,可选):引用的文档URI(仅用于引用)
- **返回**:
- 操作状态和更新的计数
**添加首选项(任意RDF三元组):**
```json
{
"status": "updated",
"preference_count": 3,
"action": "add",
"triple_type": "preference"
}
```
**添加引用(到另一个文档的链接):**
```json
{
"status": "success",
"message": "Reference added",
"added": true,
"action": "add",
"triple_type": "reference"
}
```
**更新元数据:**
```json
{
"status": "updated",
"action": "add",
"triple_type": "metadata"
}
```
**删除引用:**
```json
{
"status": "updated",
"reference_count": 2,
"action": "remove",
"triple_type": "reference"
}
```
#### `kb_search`
使用文本查询和/或图展开搜索知识库。
- **参数**:
- `query`(字符串,可选):语义搜索和重新排序的文本查询
- `seed_uris`(数组,可选):图展开的起始完整URI(kb://namespace/collection/name)
- `root_uri`(字符串,可选):部分URI(kb://namespace 或 kb://namespace/collection),用于限定搜索范围
- `expand_hops`(整数,可选):要展开的关系跳数(默认:0)
- `filter_uris`(数组,可选):要从结果中排除的URI
- `relation_predicates`(数组,可选):遍历图时要遵循的谓词(默认:["references"])
- `top_k_sparse`(整数,可选):要检索的稀疏搜索结果数(默认:50)
- `top_k_rerank`(整数,可选):重新排序后的最终结果数(默认:10)
- `include_content`(布尔值,可选):是否包含文档内容(默认:false)
- `include_index`(布尔值,可选):是否包含文档元数据(默认:false)
- `use_reranker`(布尔值,可选):是否使用语义重新排序(默认:true)
- **返回**:
- 搜索结果的排名列表
```json
{
"results": [
{
"urn": "kb://projects/docs/api-reference",
"sparse_score": 1.95,
"content": "API reference content...",
"index": {
"namespace": "projects",
"collection": "docs",
"name": "api-reference",
"type": "document",
"subtype": "text",
"created_at": "2025-07-02T23:13:17.362283Z",
"updated_at": "2025-07-02T23:18:23.396660Z",
"content_type": "text/plain",
"chunked": false,
"fragments": {},
"preferences": [],
"references": [
[
"references",
"kb://project/docs/api-dto"
]
],
"referenced_by": [],
"indices": [],
"metadata": {
"purpose": "testing_collection_organization",
"created_for": "kb_exercise",
"type": "test_document",
"created_date": "2025-07-02",
"topic": "search_performance",
"related_to": "rebuild_test"
}
},
"rerank_score": 0.84,
}
],
"count": 1
}
```
#### `kb_manage`
管理知识库操作,如移动文档和重建搜索索引。
- **参数**:
- `action`(字符串,必填):要执行的管控操作
- `"move_document"`:移动文档
- `"delete"`:归档文档
- `"rebuild_search_index"`:重建搜索索引
- `options`(对象,必填):操作特定的选项
- 对于 `"move_document"`:`{"uri": "...", "new_uri": "..."}`
- 对于 `"delete"`:`{"uri": "..."}`
- 对于 `"rebuild_search_index"`:`{"rebuild_all": true}`(可选)
- **返回**:
- 操作状态和结果
**移动文档:**
```json
{
"action": "move_document",
"status": "success",
"old_path": "projects/docs/old-name",
"new_path": "projects/docs/new-name",
"result": {
"namespace": "projects",
"collection": "docs",
"name": "new-name",
"type": "document",
"subtype": "text",
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:50:00.000Z",
"content_type": "text/plain",
"chunked": false,
"fragments": {},
"preferences": [],
"references": [],
"referenced_by": [],
"indices": [],
"metadata": {}
}
}
```
**归档文档:**
```json
{
"action": "delete",
"status": "success",
"path": "projects/docs/obsolete",
"result": {
"status": "archived",
"message": "Document archived: kb://projects/docs/obsolete",
"original_path": "projects/docs/obsolete",
"archive_path": "archive/projects/docs/obsolete",
"archive_urn": "kb://archive/projects/docs/obsolete"
}
}
```
### 列表操作
列表系统提供基于org-mode的任务、笔记、购物和一般集合的列表管理。列表支持各种项目状态,可以通过标签进行组织。
#### 项目状态
列表中的项目可以具有以下状态:`TODO`、`DONE`、`WAITING`、`CANCELLED`、`NEXT`、`SOMEDAY`
#### 列表类型
列表可以是以下类型之一:`todo`、`shopping`、`notes`、`checklist`、`project`、`reading`、`ideas`
#### `list_create`
创建新的有组织的任务、笔记、购物或任意集合的列表。
- **参数**:
- `name`(字符串,必填):列表的内部名称(用于文件名)
- `title`(字符串,可选):列表的显示标题
- `list_type`(字符串,可选):列表类型(默认为"todo")
- `description`(字符串,可选):可选描述
- `tags`(数组,可选):用于组织的标签
- `properties`(对象,可选):自定义用户定义的属性
- **返回**:
- `success`(布尔值):创建是否成功
- `name`(字符串):列表名称
- `metadata`(对象):标题、类型、创建时间、属性
- `path`(字符串):文件路径
```json
{
"success": true,
"name": "grocery-list",
"metadata": {
"title": "Weekly Groceries",
"type": "shopping",
"created": "2024-01-15T10:30:00.000Z",
"properties": {}
},
"path": "/app/lists/grocery-list.org"
}
```
#### `list_get`
使用灵活的过滤选项检索和浏览列表。
- **参数**:
- `name`(字符串,可选):要检索的特定列表名称。如果省略,则列出所有可用列表。
- `include_items`(布尔值,可选):是否在响应中包含项目(默认为true)
- `summary_only`(布尔值,可选):仅返回摘要统计信息而不返回项目(默认为false)
- `status_filter`(字符串,可选):按状态筛选项目(TODO、DONE、WAITING、CANCELLED、NEXT、SOMEDAY)
- `tag_filter`(数组,可选):按标签筛选项目(项目必须具有所有指定的标签)
- **返回**:
- 当省略`name`时:`lists`(摘要数组)、`count`
- 当提供`name`时:`name`、`metadata`、`items`、`statistics`
**列出所有列表:**
```json
{
"success": true,
"lists": [
{"name": "grocery-list", "title": "Weekly Groceries", "type": "shopping"},
{"name": "project-tasks", "title": "Q1 Tasks", "type": "todo"}
],
"count": 2
}
```
**获取特定列表:**
```json
{
"success": true,
"name": "project-tasks",
"metadata": {"title": "Q1 Tasks", "type": "todo"},
"items": [
{
"text": "Complete API integration",
"status": "TODO",
"index": 0,
"tags": ["backend"],
"created": "2024-01-15T10:30:00.000Z",
"completed": null,
"properties": {}
}
],
"statistics": {
"total_items": 5,
"status_counts": {"TODO": 3, "DONE": 2},
"completion_percentage": 40.0
}
}
```
#### `list_modify`
通过添加、更新或删除项目来修改列表项目。
- **参数**:
- `list_name`(字符串,必填):列表名称
- `action`(字符串,必填):要执行的操作("add"、"update"或"remove")
- `item_text`(字符串,可选):项目文本(对于"add"必填,对于"update"可选)
- `item_index`(整数,可选):项目索引(对于"update"和"remove"必填)
- `status`(字符串,可选):项目状态(TODO、DONE、WAITING、CANCELLED、NEXT、SOMEDAY)
- `tags`(数组,可选):项目标签
- `properties`(对象,可选):自定义属性
- **返回**:
- `success`(布尔值):操作是否成功
- `action`(字符串):执行的动作
- `item`(对象):受影响的项目详情
**添加项目:**
```json
{
"success": true,
"action": "add",
"item": {
"text": "Buy milk",
"status": "TODO",
"index": 3,
"tags": ["dairy"]
},
"total_items": 4
}
```
**更新项目:**
```json
{
"success": true,
"action": "update",
"item_index": 0,
"item": {"text": "Buy milk", "status": "DONE"},
"old_item": {"text": "Buy milk", "status": "TODO"}
}
```
**删除项目:**
```json
{
"success": true,
"action": "remove",
"removed_item": {"text": "Buy milk", "status": "DONE", "index": 0},
"remaining_items": 3
}
```
#### `list_update`
更新列表属性和元数据。属性使用合并语义 - 仅更新提供的键,现有键保留。
- **参数**:
- `name`(字符串,必填):列表名称
- `title`(字符串,可选):新标题
- `list_type`(字符串,可选):新列表类型
- `description`(字符串,可选):新描述
- `tags`(数组,可选):新标签(替换现有标签)
- `author`(字符串,可选):新作者
- `properties`(对象,可选):自定义属性(与现有属性合并)
- **返回**:
- `success`(布尔值):更新是否成功
- `name`(字符串):列表名称
- `metadata`(对象):更新后的元数据
```json
{
"success": true,
"name": "project-tasks",
"metadata": {
"title": "Q1 Tasks - Updated",
"type": "project",
"tags": ["work", "q1"],
"description": "Updated project task list"
}
}
```
#### `list_delete`
永久删除整个列表及其所有项目。列表文件将被归档以确保安全,但列表将不再通过正常操作可访问。
- **参数**:
- `name`(字符串,必填):要删除的列表名称
- **返回**:
- `success`(布尔值):删除是否成功
- `name`(字符串):已删除的列表名称
- `items_count`(整数):列表中的项目数量
- `archived_to`(字符串):归档文件路径
```json
{
"success": true,
"name": "old-grocery-list",
"items_count": 12,
"archived_to": "/app/lists/.archive/old-grocery-list.org"
}
```
#### `list_search`
按文本或标签搜索多个列表中的项目。
- **参数**:
- `query`(字符串,必填):搜索查询字符串
- `list_names`(数组,可选):要搜索的特定列表(如果省略,则搜索所有列表)
- `search_in`(数组,可选):搜索位置:"text"、"tags"或两者(默认为["text"])
- `case_sensitive`(布尔值,可选):搜索是否区分大小写(默认为false)
- **返回**:
- `matches`(数组):匹配的项目及其列表上下文
- `total_matches`(整数):匹配总数
- `lists_searched`(整数):搜索的列表数量
- `search_options`(对象):应用的搜索参数
```json
{
"success": true,
"query": "milk",
"matches": [
{
"list_name": "grocery-list",
"list_title": "Weekly Groceries",
"item_index": 2,
"item_text": "Buy milk",
"item_status": "TODO",
"item_tags": ["dairy"],
"match_type": "text"
}
],
"total_matches": 1,
"lists_searched": 3,
"search_options": {
"search_in": ["text"],
"case_sensitive": false
}
}
```
### 市场操作
市场系统使用Yahoo Finance提供股票和加密货币的金融数据查询。
#### `market_query`
查询股票或加密货币的价格,并提供基本面、新闻和趋势分析。
- **参数**:
- `symbol`(字符串,必填):股票/加密货币符号(例如"AAPL"、"BTC-USD"、"TSLA")
- `period`(字符串,可选):趋势指标的历史周期(默认为"1y")
- `interval`(字符串,可选):历史数据间隔(默认为"1d")
- `news_count`(整数,可选):返回的最新新闻项目数量(默认为5)
- **返回**:
- `symbol`(字符串):查询的符号
- `name`(字符串):公司/资产名称
- `price`(浮点数):当前价格
- `change`(浮点数):价格变化
- `change_percent`(浮点数):百分比变化
- `volume`(整数):交易量
- `market_cap`(整数):市值
- `currency`(字符串):货币代码
- `timestamp`(字符串):ISO格式的时间戳
- `fundamentals`(对象):盈利、PE比率、股息、利润率
- `news`(数组):最新新闻项目
- `trend`(对象):移动平均线、RSI、波动率、历史回报
- `success`(布尔值):查询是否成功
- `error`(字符串):如果查询失败,则为错误消息
```json
{
"symbol": "AAPL",
"name": "Apple Inc.",
"price": 185.92,
"change": 2.35,
"change_percent": 1.28,
"volume": 54321000,
"market_cap": 2890000000000,
"currency": "USD",
"timestamp": "2024-01-15T16:00:00Z",
"fundamentals": {
"trailing_pe": 29.5,
"forward_pe": 27.8,
"dividend_yield": 0.0054,
"profit_margin": 0.256,
"earnings_quarterly_growth": 0.13
},
"news": [
{
"title": "Apple Reports Strong Q4 Earnings",
"link": "https://example.com/article",
"publisher": "Reuters",
"published": "2024-01-15T12:00:00Z",
"type": "STORY"
}
],
"trend": {
"as_of": "2024-01-15T16:00:00Z",
"close": 185.92,
"return_1w": 0.023,
"return_1m": 0.045,
"return_3m": 0.12,
"ma20": 183.50,
"ma50": 180.25,
"ma200": 175.80,
"rsi14": 58.3,
"volatility_20d": 0.18,
"range_52w_low": 164.08,
"range_52w_high": 199.62,
"data_points": 252
},
"success": true,
"error": null
}
```
### RSS 操作
RSS系统获取并解析RSS和Atom馈流。
#### `rss_fetch`
获取并解析RSS或Atom馈流,返回结构化项目。
- **参数**:
- `url`(字符串,必填):RSS馈流URL
- `limit`(整数,可选):返回的最大项目数(默认为10)
- **返回**:
- `feed_title`(字符串):馈流标题
- `feed_link`(字符串):馈流网站链接
- `items`(数组):馈流项目,每个项目包含:
- `title`(字符串):项目标题
- `link`(字符串):项目URL
- `published`(字符串):发布时间
- `summary`(字符串):项目摘要/描述
- `item_count`(整数):返回的项目数量
- `success`(布尔值):获取是否成功
- `error`(字符串):如果获取失败,则为错误消息
```json
{
"feed_title": "Hacker News",
"feed_link": "https://news.ycombinator.com",
"items": [
{
"title": "Show HN: A new open-source project",
"link": "https://example.com/project",
"published": "2024-01-15T14:30:00Z",
"summary": "An innovative approach to solving..."
}
],
"item_count": 10,
"success": true,
"error": null
}
```
## 架构
该项目遵循模块化架构:
```bash
container-mcp/
├── cmcp/ # 主应用程序代码
│ ├── managers/ # 领域特定管理器
│ │ ├── bash_manager.py # 安全的bash执行
│ │ ├── file_manager.py # 安全的文件操作
│ │ ├── knowledge_base_manager.py # 知识库操作
│ │ ├── list_manager.py # 列表/集合操作
│ │ ├── market_manager.py # 市场数据操作
│ │ ├── python_manager.py # 安全的python执行
│ │ ├── rss_manager.py # RSS源操作
│ │ └── web_manager.py # 安全的网络操作
│ ├── kb/ # 知识库组件
│ │ ├── document_store.py # 文档存储和检索
│ │ ├── models.py # 数据模型和模式
│ │ ├── path.py # 路径解析和验证
│ │ └── search.py # 搜索索引和排名
│ ├── tools/ # MCP工具实现
│ │ ├── file.py # 文件操作工具
│ │ ├── kb.py # 知识库工具
│ │ ├── list.py # 列表操作工具
│ │ ├── market.py # 市场数据工具
│ │ ├── rss.py # RSS源工具
│ │ ├── system.py # 系统操作工具
│ │ └── web.py # 网络操作工具
│ ├── utils/ # 实用函数
│ │ ├── diff.py # 差异/补丁实用工具
│ │ ├── io.py # 输入/输出助手
│ │ └── logging.py # 日志实用工具
│ ├── __init__.py
│ ├── config.py # 配置系统
│ └── main.py # MCP服务器设置
├── apparmor/ # AppArmor配置文件
│ ├── mcp-bash # Bash执行配置文件
│ └── mcp-python # Python执行配置文件
├── bin/ # 构建/运行脚本
│ ├── 00-all-in-one.sh # 完整设置脚本
│ ├── 01-init.sh # 项目初始化
│ ├── 02-build-container.sh # 容器构建脚本
│ ├── 03-setup-environment.sh # 环境设置
│ ├── 04-run-container.sh # 容器运行脚本
│ ├── 05-check-container.sh # 容器健康检查
│ ├── 06-run-tests.sh # 测试执行
│ ├── 07-attach-container.sh # 容器shell访问
│ ├── 08-testnetwork.sh # 网络测试
│ ├── 09-view-logs.sh # 日志查看
│ ├── zy-shutdown.sh # 容器关闭
│ └── zz-teardown.sh # 完整拆除
├── tests/ # 测试套件
│ ├── integration/ # 集成测试
│ ├── unit/ # 单元测试
│ └── conftest.py # 测试配置
├── volume/ # 持久存储
│ ├── config/ # 配置文件
│ ├── data/ # 数据目录
│ ├── kb/ # 知识库存储
│ │ ├── search/ # 搜索索引
│ │ │ ├── sparse_idx/ # 稀疏搜索索引
│ │ │ └── graph_idx/ # 图搜索索引
│ │ ├── archive/ # 存档文档
│ ├── logs/ # 日志文件
│ ├── sandbox/ # 沙盒执行空间
│ │ ├── bash/ # Bash沙盒
│ │ ├── browser/ # 网络浏览器沙盒
│ │ ├── files/ # 文件操作沙盒
│ │ └── python/ # Python沙盒
│ └── temp/ # 临时存储
├── Containerfile # 容器定义
├── podman-compose.yml # 容器编排
├── pyproject.toml # Python项目配置
├── uv.lock # 依赖锁定文件
├── pytest.ini # 测试配置
└── README.md # 项目文档
```
每个管理器都遵循一致的设计模式:
- `.from_env()` 类方法用于基于环境的初始化
- 异步执行方法用于非阻塞操作
- 强大的输入验证和错误处理
- 所有操作都优先考虑安全性
## 安全措施
Container-MCP实施了多层安全措施:
1. **容器隔离**: 使用Podman/Docker进行容器隔离
2. **AppArmor配置文件**: 为bash和Python执行提供细粒度访问控制
3. **Firejail沙盒**: 额外的进程隔离
4. **资源限制**: 内存、CPU和执行时间限制
5. **路径遍历预防**: 验证和规范所有文件路径
6. **允许扩展限制**: 控制可以访问的文件类型
7. **网络限制**: 控制可以访问的域名
8. **最小特权**: 组件以最小必要的权限运行
## 安装
### 先决条件
- 具有Podman或Docker的Linux系统
- Python 3.12+
- Firejail (`apt install firejail` 或 `dnf install firejail`)
- AppArmor (`apt install apparmor apparmor-utils` 或 `dnf install apparmor apparmor-utils`)
### 快速入门
开始使用最快的方法是使用一体化脚本:
```bash
git clone https://github.com/54rt1n/container-mcp.git
cd container-mcp
chmod +x bin/00-all-in-one.sh
./bin/00-all-in-one.sh
```
### 分步安装
您也可以单独执行安装步骤:
1. **初始化项目**:
```bash
./bin/01-init.sh
```
2. **构建容器**:
```bash
./bin/02-build-container.sh
```
3. **设置环境**:
```bash
./bin/03-setup-environment.sh
```
4. **运行容器**:
```bash
./bin/04-run-container.sh
```
5. **运行测试**(可选):
```bash
./bin/05-run-tests.sh
```
## 使用
一旦容器运行,您就可以使用任何MCP客户端实现连接到它。服务器将在`http://localhost:8000`或您在配置中指定的端口上可用。
**重要:** 在配置MCP客户端时,您必须将端点URL设置为`http://127.0.0.1:<port>/sse`(其中`<port>`默认为8000或您配置的端口)。`/sse`路径对于正确的服务器发送事件通信是必需的。
### Python客户端示例
```python
from mcp.client.sse import sse_client
from mcp import ClientSession
import asyncio
async def main():
# 连接到Container-MCP服务器
# 注意所需的/sse端点后缀用于SSE通信
sse_url = "http://127.0.0.1:8000/sse" # 或您配置的端口
# 连接到SSE端点
async with sse_client(sse_url) as (read, write):
async with ClientSession(read, write) as session:
# 初始化连接
await session.initialize()
# 发现可用工具
result = await session.list_tools()
print(f"可用工具:{[tool.name for tool in result.tools]}")
# 执行Python脚本
python_result = await session.execute_tool(
"system_run_python",
{"code": "print('Hello, world!')\nresult = 42\n_ = result"}
)
print(f"Python结果:{python_result}")
# 执行bash命令
bash_result = await session.execute_tool(
"system_run_command",
{"command": "ls -la"}
)
print(f"命令输出:{bash_result['stdout']}")
if __name__ == "__main__":
asyncio.run(main())
```
## 配置
Container-MCP可以通过环境变量进行配置,这些变量可以在`volume/config/custom.env`中设置:
### 服务器配置
```
# MCP服务器配置
MCP_HOST=127.0.0.1
MCP_PORT=9001
DEBUG=true
LOG_LEVEL=INFO
```
### Bash管理器配置
```
# Bash管理器配置
BASH_ALLOWED_COMMANDS=ls,cat,grep,find,echo,pwd,mkdir,touch
BASH_TIMEOUT_DEFAULT=30
BASH_TIMEOUT_MAX=120
```
### Python管理器配置
```
# Python管理器配置
PYTHON_MEMORY_LIMIT=256
PYTHON_TIMEOUT_DEFAULT=30
PYTHON_TIMEOUT_MAX=120
```
### 文件管理器配置
```
# 文件管理器配置
FILE_MAX_SIZE_MB=10
FILE_ALLOWED_EXTENSIONS=txt,md,csv,json,py
```
### 网络管理器配置
```
# 网络管理器配置
WEB_TIMEOUT_DEFAULT=30
WEB_ALLOWED_DOMAINS=*
```
### 知识库管理器配置
```
# 知识库管理器配置
CMCP_KB_STORAGE_PATH=/app/kb
KB_TIMEOUT_DEFAULT=30
KB_TIMEOUT_MAX=120
# 搜索配置
CMCP_KB_SEARCH_ENABLED=true
CMCP_KB_SPARSE_INDEX_PATH=/app/kb/search/sparse_idx
CMCP_KB_GRAPH_INDEX_PATH=/app/kb/search/graph_idx
CMCP_KB_RERANKER_MODEL=mixedbread-ai/mxbai-rerank-base-v1
CMCP_KB_SEARCH_RELATION_PREDICATES=references
CMCP_KB_SEARCH_GRAPH_NEIGHBOR_LIMIT=1000
# 工具启用/禁用
TOOLS_ENABLE_KB=true
```
### 列表管理器配置
```
# 列表管理器配置
CMCP_LIST_STORAGE_PATH=/app/lists
TOOLS_ENABLE_LIST=true
```
### 市场管理器配置
```
# 市场管理器配置
MARKET_TIMEOUT_DEFAULT=30
MARKET_TIMEOUT_MAX=60
TOOLS_ENABLE_MARKET=true
```
### RSS管理器配置
```
# RSS管理器配置
RSS_TIMEOUT_DEFAULT=15
RSS_TIMEOUT_MAX=30
RSS_USER_AGENT=container-mcp/1.0
TOOLS_ENABLE_RSS=true
```
## 开发
### 设置开发环境
1. 创建Python虚拟环境:
```bash
python3.12 -m venv .venv
source .venv/bin/activate
```
2. 安装依赖项:
```bash
pip install -r requirements-dev.txt
```
3. 以开发模式安装包:
```bash
pip install -e .
```
### 运行测试
```bash
# 运行所有测试
pytest
# 仅运行单元测试
pytest tests/unit
# 仅运行集成测试
pytest tests/integration
# 运行覆盖率报告
pytest --cov=cmcp --cov-report=term --cov-report=html
```
### 开发服务器
在开发模式下运行MCP服务器:
```bash
python -m cmcp.main --test-mode
```
## 许可证
该项目在Apache License 2.0下获得许可。
## 作者
Martin Bukowski
连接信息
猜你喜欢
暂无推荐服务器