使用说明

上下文

LLM代理的上下文文件系统服务器/客户端 --MCP兼容、多租户、零依赖仪表板。

作者：哈维尔·莱安德罗·阿兰西比亚-- 内联网fr · arancibiajav@gmail.com

建筑

graph TD
    Agent[LLM Agent] -->|MCP SSE/Stdio| Server[ContextFS Server]
    Server -->|WebSocket| WS1[WS Client A]
    Server -->|WebSocket| WS2[WS Client B]
    WS1 -->|Sandboxed| FS1[Workspace A1]
    WS1 -->|Sandboxed| FS2[Workspace A2]

ContextFS遵循 轮毂和辐条 架构：

服务器（集线器）：管理身份验证、虚拟客户端注册和粘性调度。
WS客户端（辐条）：在沙盒环境中物理执行工具调用。
本地模式：对于单机使用，服务器充当自己的辐条。

什么是contextfs？

contextfs 为LLM代理人提供 持久、结构化的文件系统 它们可以读取、写入和搜索，而无需直接访问您的计算机。

它揭示了一个标准 MCP（模型上下文协议） 通过SSE或stdio进行表面处理，因此任何兼容MCP的LLM客户端（Claude Desktop、Cursor、自定义代理）都可以开箱即用。

关键概念

概念	描述
WS客户端	物理执行工具调用的机器/过程。通过WebSocket连接到服务器。
虚拟客户端	逻辑租户（代理、用户、项目）。拥有自己的API密钥、工作空间、技能和内存。同一WS客户端可以为多个VC提供服务。
工作区	作用域为虚拟客户端的目录。所有文件操作都在其中沙盒
本地模式	服务器在进程内执行工具——不需要WS客户端。非常适合单机使用。

快速开始

选项A——本地模式（最简单的单机）

npx contextfs server --local --mcp sse

# Create a virtual client
curl -s -X POST http://localhost:3010/api/virtual-clients \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent"}' | jq .
# → copy "id" and "apiKey"

# Open dashboard
open http://localhost:3010

# Chat
CONTEXTFS_VC_ID=<id> CONTEXTFS_VC_KEY=<key> OPENROUTER_API_KEY=sk-or-... \
  npx contextfs chat --mcp-server http://localhost:3010

选项B——远程WS客户端模式

# Terminal 1 — server
npx contextfs server --mcp sse

# Terminal 2 — create entities
curl -s -X POST http://localhost:3010/api/ws-clients \
  -H 'Content-Type: application/json' -d '{"name":"worker-1"}' | jq .
# → copy wsc id + apiKey

curl -s -X POST http://localhost:3010/api/virtual-clients \
  -H 'Content-Type: application/json' -d '{"name":"agent-1"}' | jq .
# → copy vc id + apiKey

# Terminal 3 — WS client (can be on a different machine)
CONTEXTFS_API_KEY=<wsc-key> \
  npx contextfs client \
    --url ws://localhost:3010 \
    --ws-client-id <wsc-id> \
    --api-key <wsc-key>

# Terminal 4 — chat
CONTEXTFS_VC_ID=<vc-id> CONTEXTFS_VC_KEY=<vc-key> OPENROUTER_API_KEY=sk-or-... \
  npx contextfs chat --mcp-server http://localhost:3010

CLI参考

`contextfs server`

contextfs server [options]

Options:
  --port <port>       HTTP + WS port (default: 3010, env: PORT)
  --local             Local mode: tools run in-process, no WS clients (env: CONTEXTFS_LOCAL=1)
  --mcp [sse]         Enable MCP server
                        (default: stdio — requires --vc-id + --vc-key)
                        (sse — VC creds per-connection: ?vcId=&vcKey= or headers)
  --vc-id <id>        Virtual client ID for stdio MCP (env: CONTEXTFS_VC_ID)
  --vc-key <key>      Virtual client API key for stdio MCP (env: CONTEXTFS_VC_KEY)
  --insecure          Enable contextfs.bash_script_once tool
  --verbose           Verbose logging

`contextfs client`

contextfs client [options]

Options:
  --url <wsUrl>         Server WebSocket URL (required, env: CONTEXTFS_SERVER_URL)
  --ws-client-id <id>   WS client ID (required, env: CONTEXTFS_WS_CLIENT_ID)
  --api-key <key>       WS client API key (required, env: CONTEXTFS_API_KEY)
  --cwd <path>          Workspace root (default: ~/.contextfs/workspaces/<wsc-id>)
  --insecure            Enable contextfs.bash_script_once
  --verbose             Verbose logging

`contextfs chat`

contextfs chat [options]

Options:
  --mcp-server <url>    MCP server base URL (default: http://localhost:3010)
  --vc-id <id>          Virtual client ID (env: CONTEXTFS_VC_ID)
  --vc-key <key>        Virtual client API key (env: CONTEXTFS_VC_KEY)
  --model <model>       LLM model via OpenRouter (env: CONTEXTFS_MODEL)
  --message <text>      Non-interactive: send single message, exit 0 (alias: -m)
  --stdin               Read message from stdin
  --output json         Output { message, toolCalls, durationMs } JSON
  --no-tools            Disable tool calls (pure LLM)
  --verbose             Verbose logging

交互式命令： /exit, /clear, /tools, /history

MCP集成

SSE（建议用于网络/代理）

GET http://localhost:3010/mcp/sse?vcId=<id>&vcKey=<key>
POST http://localhost:3010/mcp/message?sessionId=<sessionId>

或者通过标题：

GET http://localhost:3010/mcp/sse
X-VC-ID: <id>
Authorization: Bearer <key>

stdio（用于克劳德桌面、光标等）

{
  "mcpServers": {
    "contextfs": {
      "command": "npx",
      "args": ["contextfs", "server", "--local", "--mcp", "--vc-id", "<id>", "--vc-key", "<key>"]
    }
  }
}

工具参考

所有工具都存放在虚拟客户端的活动工作区根目录中。

工具	说明
`contextfs.list`	列出文件/目录。支持递归、深度、全局过滤器。（RTK优化）
`contextfs.read`	读取文件内容。支持行范围、字节限制和大文件（>500行）的自动过滤.
`contextfs.summarize`	新以90%的令牌成本获得代码文件（签名、文档字符串、复杂性）的智能摘要。
`contextfs.write`	写入或附加到文件。
`contextfs.list_workspaces`	列出当前虚拟客户端的可用工作区。
`contextfs.use_workspace`	切换当前会话的活动工作区。
`contextfs.save_skill`	将可重用技能另存为Markdown `/skills/`.
`contextfs.list_skills`	列出技能，可选择按标签筛选。
`contextfs.save_memory`	将内存条目持久化 `/memory/YYYY/MM/`.
`contextfs.search_memory`	在所有内存文件中进行全文关键字搜索。
`contextfs.memory_summary`	所有内存条目的元数据摘要。
`contextfs.memory_by_date`	检索特定年份/月份的记忆。
`contextfs.memory_by_tag`	查找带有特定标签的所有记忆。
`contextfs.bash_script_once`	执行一次性bash脚本（需要 `--insecure`). （RTK针对测试进行了优化）

RTK集成（令牌优化）

ContextFS集成 RTK（Rust令牌杀手）当代理与文件系统交互时，显著减少令牌消耗（60-90%）。

运作原理

在Docker容器中运行时，或者 rtk 二进制文件可用：

核心命令: ls, grep, git，以及 docker 通过RTK自动代理，以剥离冗余的元数据和格式。
测试优化: npm test, cargo test，以及 pytest 输出经过过滤，仅显示前5个故障和摘要，防止大型套件上的令牌爆炸。
智能摘要：The contextfs.summarize 该工具利用RTK的结构分析来提供代码概述，而无需读取完整的文件内容。
超紧凑模式：通过设置施加最大压缩力 CONTEXTFS_RTK_ULTRA_COMPACT=true 或通过 -u 标记支持的命令。

本土撤退

集成是非侵入性的。如果RTK不可用、失败或不支持命令，ContextFS会自动回退到本机执行以确保可靠性。

REST API参考

基本URL: http://localhost:3010/api

WS客户端

GET    /api/ws-clients                        List all WS clients
POST   /api/ws-clients                        Create WS client → returns apiKey (once)
DELETE /api/ws-clients/:id                    Delete WS client
POST   /api/ws-clients/:id/regen-key          Regenerate API key → returns new apiKey

虚拟客户端

GET    /api/virtual-clients                   List all virtual clients
POST   /api/virtual-clients                   Create virtual client → returns apiKey (once)
DELETE /api/virtual-clients/:id               Delete virtual client + owned workspaces
POST   /api/virtual-clients/:id/regen-key     Regenerate API key

工作区

GET    /api/virtual-clients/:vcId/workspaces              List workspaces
POST   /api/virtual-clients/:vcId/workspaces              Create workspace
DELETE /api/virtual-clients/:vcId/workspaces/:wsId        Delete workspace

派遣

POST /api/dispatch
Body: { virtualClientId, virtualClientApiKey, tool, params, timeoutMs? }

向分配的WS客户端发出工具调用并等待响应。

状态+MCP

GET /api/status          Summary counts
GET /mcp/sessions        Active MCP SSE sessions

安全模型

WS客户端API密钥 --对每个WS连接进行身份验证。对每条WebSocket消息进行验证。
虚拟客户端API密钥 --验证MCP会话(?vcKey=)以及REST调度调用。每个虚拟客户端都与其他客户端完全隔离。
路径沙盒 --所有文件操作都在工作区根目录中解析。任何路径遍历尝试(../)返回错误。
bash_script_once --默认情况下禁用。需要明确 --insecure 服务器和客户端上的标记。
API密钥只显示一次 --关于创造与再生。立即储存。

文档

MIGRATION.md --从原型升级到v1。
跑步手册.md --操作指南、缩放和维护。

仪表盘

打开 http://localhost:3010 启动服务器后。仪表板显示：

具有实时状态、CPU负载、RAM使用率、心跳时间的WS客户端
具有分配状态的虚拟客户端
每个虚拟客户端的工作区
活动MCP会话

无需登录——在具有身份验证的反向代理后提供服务，以供生产使用。

数据目录

所有国家都坚持 ~/.contextfs/:

~/.contextfs/
├── ws-clients.json         WS client registry
├── virtual-clients.json    Virtual client registry
├── workspaces.json         Workspace registry
├── chat-config.json        Chat TUI config (API key, model)
├── .machine-id             Persistent client identity
└── workspaces/
    └── <vcId>/
        └── <wsId>/
            ├── skills/     Saved skills (.md files)
            ├── memory/     Memory entries (YYYY/MM/*.md)
            └── ...         Your files

环境变量

变量	描述	默认值
`PORT`	服务器HTTP端口	`3010`
`CONTEXTFS_LOCAL`	启用本地模式(`1`)	—
`CONTEXTFS_INSECURE`	启用bash_script_once(`1`)	—
`CONTEXTFS_SERVER_URL`	客户端的WS服务器URL	--
`CONTEXTFS_WS_CLIENT_ID`	WS客户端ID	--
`CONTEXTFS_API_KEY`	WS客户端API密钥	-
`CONTEXTFS_VC_ID`	聊天/MCP的虚拟客户端ID	--
`CONTEXTFS_VC_KEY`	用于聊天/MCP的虚拟客户端API密钥	-
`CONTEXTFS_MCP_SERVER`	聊天的MCP服务器基本URL	`http://localhost:3010`
`CONTEXTFS_MODEL`	LLM聊天模型	`google/gemini-2.5-flash-preview`
`OPENROUTER_API_KEY`	用于聊天的OpenRouter API密钥	-
`CONTEXTFS_RTK_ENABLED`	启用RTK优化(`true`/`false`)	`true` （自动检测）
`CONTEXTFS_RTK_ULTRA_COMPACT`	启用超紧凑模式(`true`)	`false`
`VERBOSE`	启用详细日志记录(`1`)	—

需求

Node.js≥18
无需构建步骤
没有本机模块

LLM代理文件系统服务

使用说明

上下文

建筑

什么是contextfs？

关键概念

快速开始

选项A——本地模式（最简单的单机）

选项B——远程WS客户端模式

CLI参考

`contextfs server`

`contextfs client`

`contextfs chat`

MCP集成

SSE（建议用于网络/代理）

stdio（用于克劳德桌面、光标等）

工具参考

RTK集成（令牌优化）

运作原理

本土撤退

REST API参考

WS客户端

虚拟客户端

工作区

派遣

状态+MCP

安全模型

文档

仪表盘

数据目录

环境变量

需求

许可证

使用说明

上下文

建筑

什么是contextfs？

关键概念

快速开始

选项A——本地模式（最简单的单机）

选项B——远程WS客户端模式

CLI参考

contextfs server

contextfs client

contextfs chat

MCP集成

SSE（建议用于网络/代理）

stdio（用于克劳德桌面、光标等）

工具参考

RTK集成（令牌优化）

运作原理

本土撤退

REST API参考

WS客户端

虚拟客户端

工作区

派遣

状态+MCP

安全模型

文档

仪表盘

数据目录

环境变量

需求

许可证

相关 MCP

文件上下文服务器

文件系统服务

文件系统操作服务器

文件系统协议服务

OpenAPI工具服务器

文件系统MCP服务器

`contextfs server`

`contextfs client`

`contextfs chat`