Contextfs 9bb5553f

MCP运维云端

提供方 javimosch · 包名 contextfs

运维云端 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaudeCursor
查看接入方式

ContextFS为LLM代理提供持久化、结构化的文件系统服务,支持读写和搜索操作,同时通过沙箱环境确保安全性。

一句话选型结论

按资料字段整理

Contextfs 9bb5553f 属于运维云端类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude、Cursor,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 14 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量14暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

LLM代理JavaScript本地部署文件系统沙箱环境多租户MCP兼容

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
npx contextfs server --local --mcp sse

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 14 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 14 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Contextfs 9bb5553f当前 14 stdio · 本地进程 本地部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方javimosch上游标注的维护方 javimosch
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时contextfs · Node.js本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

11.8 KB
来自项目仓库与上游目录的原文,未做删改

contextfs

Context filesystem server/client for LLM agents — MCP-compatible, multi-tenant, zero-dependency dashboard.

> Author: Javier Leandro Arancibia — intrane.fr · arancibiajav@gmail.com


Architecture```mermaid

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 follows a **Hub-and-Spoke** architecture:
- **Server (Hub)**: Manages authentication, virtual client registration, and sticky scheduling.
- **WS Client (Spoke)**: Physically executes tool calls in a sandboxed environment.
- **Local Mode**: For single-machine use, the server acts as its own spoke.

---

## What is contextfs?

`contextfs` gives LLM agents a **persistent, structured filesystem** they can read from, write to, and search — without giving them direct access to your machine.

It exposes a standard **MCP (Model Context Protocol)** surface over SSE or stdio, so any MCP-compatible LLM client (Claude Desktop, Cursor, custom agents) can use it out of the box.

### Key concepts

| Concept | Description |
|---|---|
| **WS Client** | A machine/process that physically executes tool calls. Connects to the server via WebSocket. |
| **Virtual Client** | A logical tenant (agent, user, project). Has its own API key, workspace, skills, and memory. Multiple VCs can be served by the same WS client. |
| **Workspace** | A directory scoped to a virtual client. All file operations are sandboxed within it. |
| **Local mode** | Server executes tools in-process — no WS client needed. Ideal for single-machine use. |

---

## Quick start

### Option A — Local mode (simplest, single machine)```bash
npx contextfs server --local --mcp sse
``````bash
# 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

Option B — Remote WS client mode```bash

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 reference

### `contextfs server````
contextfs server [options]

Options:
  --port &lt;port&gt;       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=&amp;vcKey= or headers)
  --vc-id &lt;id&gt;        Virtual client ID for stdio MCP (env: CONTEXTFS_VC_ID)
  --vc-key &lt;key&gt;      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 &lt;url&gt;    MCP server base URL (default: http://localhost:3010)
  --vc-id &lt;id&gt;          Virtual client ID (env: CONTEXTFS_VC_ID)
  --vc-key &lt;key&gt;        Virtual client API key (env: CONTEXTFS_VC_KEY)
  --model &lt;model&gt;       LLM model via OpenRouter (env: CONTEXTFS_MODEL)
  --message &lt;text&gt;      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

Interactive commands: /exit, /clear, /tools, /history


MCP integration

SSE (recommended for web/agent use)```

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


Or via headers:```
GET http://localhost:3010/mcp/sse
X-VC-ID: &lt;id&gt;
Authorization: Bearer &lt;key&gt;

stdio (for Claude Desktop, Cursor, etc.)```json

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


---

## Tools reference

All tools are sandboxed within the virtual client&#x27;s active workspace root.

| Tool | Description |
|---|---|
| `contextfs.list` | List files/directories. Supports recursive, depth, glob filter. **(RTK Optimized)** |
| `contextfs.read` | Read file content. Supports line ranges, byte limits, and **automatic filtering for large files (&gt;500 lines)**. |
| `contextfs.summarize` | **(New)** Get an intelligent summary of a code file (signatures, docstrings, complexity) at 90% lower token cost. |
| `contextfs.write` | Write or append to a file. |
| `contextfs.list_workspaces` | List available workspaces for the current virtual client. |
| `contextfs.use_workspace` | Switch the active workspace for the current session. |
| `contextfs.save_skill` | Save a reusable skill as Markdown under `/skills/`. |
| `contextfs.list_skills` | List skills, optionally filtered by tag. |
| `contextfs.save_memory` | Persist a memory entry under `/memory/YYYY/MM/`. |
| `contextfs.search_memory` | Full-text keyword search across all memory files. |
| `contextfs.memory_summary` | Metadata summary of all memory entries. |
| `contextfs.memory_by_date` | Retrieve memories from a specific year/month. |
| `contextfs.memory_by_tag` | Find all memories with a specific tag. |
| `contextfs.bash_script_once` | Execute a one-shot bash script (requires `--insecure`). **(RTK Optimized for tests)** |

---

## RTK Integration (Token Optimization)

ContextFS integrates RTK (Rust Token Killer) to significantly reduce token consumption (60-90%) when agents interact with the filesystem.

### How it works
When running in a Docker container or where the `rtk` binary is available:
- **Core Commands**: `ls`, `grep`, `git`, and `docker` are automatically proxied through RTK to strip redundant metadata and formatting.
- **Test Optimization**: `npm test`, `cargo test`, and `pytest` outputs are filtered to show only the first 5 failures and a summary, preventing token blowup on large suites.
- **Intelligent Summarization**: The `contextfs.summarize` tool leverages RTK&#x27;s structural analysis to provide code overviews without reading full file content.
- **Ultra-Compact Mode**: Force maximum compression by setting `CONTEXTFS_RTK_ULTRA_COMPACT=true` or passing the `-u` flag to supported commands.

### Native Fallback
Integration is non-intrusive. If RTK is unavailable, fails, or a command is not supported, ContextFS automatically falls back to native execution to ensure reliability.

---

## REST API reference

Base URL: `http://localhost:3010/api`

### WS Clients```
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

Virtual Clients```

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


### Workspaces```
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

Dispatch```

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


Dispatches a tool call to the assigned WS client and waits for the response.

### Status + MCP```
GET /api/status          Summary counts
GET /mcp/sessions        Active MCP SSE sessions

Security model

  • WS client API keys — authenticate each WS connection. Validated on every WebSocket message.
  • Virtual client API keys — authenticate MCP sessions (?vcKey=) and REST dispatch calls. Each virtual client is fully isolated from others.
  • Path sandboxing — all file operations are resolved within the workspace root. Any path traversal attempt (../) returns an error.
  • bash_script_once — disabled by default. Requires explicit --insecure flag on both server and client.
  • API keys are shown only once — on creation and on regen. Store them immediately.

Documentation

  • MIGRATION.md — Upgrading from prototypes to v1.
  • RUNBOOK.md — Operational guide, scaling, and maintenance.

Dashboard

Open http://localhost:3010 after starting the server. The dashboard shows:
- WS clients with live status, CPU load, RAM usage, heartbeat time
- Virtual clients with assignment status
- Workspaces per virtual client
- Active MCP sessions

No login required — serve behind a reverse proxy with authentication for production use.


Data directory

All state is persisted to ~/.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/ └── &lt;vcId&gt;/ └── &lt;wsId&gt;/ ├── skills/ Saved skills (.md files) ├── memory/ Memory entries (YYYY/MM/*.md) └── ... Your files


Environment variables

Variable Description Default
PORT Server HTTP port 3010
CONTEXTFS_LOCAL Enable local mode (1) —
CONTEXTFS_INSECURE Enable bash_script_once (1) —
CONTEXTFS_SERVER_URL WS server URL for client —
CONTEXTFS_WS_CLIENT_ID WS client ID —
CONTEXTFS_API_KEY WS client API key —
CONTEXTFS_VC_ID Virtual client ID for chat/MCP —
CONTEXTFS_VC_KEY Virtual client API key for chat/MCP —
CONTEXTFS_MCP_SERVER MCP server base URL for chat http://localhost:3010
CONTEXTFS_MODEL LLM model for chat google/gemini-2.5-flash-preview
OPENROUTER_API_KEY OpenRouter API key for chat —
CONTEXTFS_RTK_ENABLED Enable RTK optimization (true/false) true (auto-detect)
CONTEXTFS_RTK_ULTRA_COMPACT Enable ultra-compact mode (true) false
VERBOSE Enable verbose logging (1) —

Requirements

  • Node.js ≥ 18
  • No build step required
  • No native modules

License

MIT © Javier Leandro Arancibia

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Contextfs 9bb5553f 怎么安装?

在客户端按下面的安装命令接入:npx contextfs server --local --mcp sse。对应的包名是 contextfs。装完在客户端配置里引用同一个包或端点。

Contextfs 9bb5553f 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Contextfs 9bb5553f 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Contextfs 9bb5553f 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Contextfs 9bb5553f 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Contextfs 9bb5553f 能提供哪些能力?

资料显示约 14 个工具;能力标签包括 LLM代理、多租户、JavaScript、Claude。具体工具清单以官方文档为准。

Contextfs 9bb5553f 需要什么运行环境?

运行时为 Node.js;属于本地进程,需要在本机装好运行环境。

Contextfs 9bb5553f 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。