slim-mcp：为AI Agent工具列表智能瘦身，节省70%上下文Token

1. 项目概述为AI Agent“瘦身”的MCP代理如果你正在使用Claude Code、Cursor或者任何支持Model Context Protocol的AI助手并且发现随着你安装的MCP服务器越来越多工具列表长得让人眼花缭乱甚至开始挤占宝贵的上下文窗口那么你遇到的情况和我之前一模一样。每次初始化时Agent都要加载几十个甚至上百个工具的完整JSON Schema这些冗长的描述占用了大量token而这些token本可以用来处理更重要的代码逻辑和对话历史。slim-mcp就是为了解决这个问题而生的。它是一个智能的MCP代理服务器核心使命就一个在不影响功能准确性的前提下最大限度地压缩和优化传递给AI Agent的工具描述信息把被工具列表吃掉的上下文窗口“抢”回来。我自己在深度使用多个MCP服务器后发现工具描述信息的冗余度极高很多字段对LLM来说并非必要完全可以通过更精巧的方式呈现。这个项目就是这种思考的工程化实践。它不是一个全新的MCP服务器而是一个“中间层”或“代理”。你可以把它想象成一个高效的“翻译官”或“调度中心”。你的AI客户端如Claude Code不再直接连接文件系统、GitHub、数据库等MCP服务器而是连接slim-mcp。slim-mcp会替你管理所有后端服务器并对它们提供的工具列表进行实时处理——压缩、懒加载、缓存——然后再将精简后的结果返回给客户端。对于客户端和LLM来说它就像一个普通的、但工具描述异常简洁的MCP服务器。2. 核心原理与设计思路拆解要理解slim-mcp的价值得先看看我们面对的问题本质。MCP协议中一个工具的定义Schema通常包含name、description、inputSchema等字段。inputSchema本身是一个完整的JSON Schema对象用于定义参数的类型、格式、描述等。当你有几十个工具时这些Schema的累加就是一个非常可观的token消耗体。2.1 问题诊断Token都浪费在哪了我最初对几个主流MCP服务器的工具列表做了分析发现几个主要的“脂肪”区域结构冗余JSON Schema本身为了表达严谨性会有很多嵌套结构如properties、items、anyOf和重复的字段名。过长的描述文本很多工具和参数的description字段写得非常详细但对于已经通过名称能理解其功能的LLM来说部分描述是冗余的。完整的类型定义inputSchema里会明确写出type: “string”type: “integer”等。但LLM在调用工具时本质上是在生成一个符合接口的JSON对象它并不需要“学习”这个JSON Schema规范它只需要知道“这里需要一个字符串类型的参数叫path”。slim-mcp的压缩策略就是针对这些“脂肪”进行精准手术。2.2 分层压缩策略从“理发”到“换头”项目提供了五个渐进的压缩等级你可以根据自己对简洁性和可读性的权衡进行选择。none(无压缩)直通模式用于基准测试和调试。standard(标准)这是默认级别进行“无害”清理。比如移除JSON Schema中LLM不关心的元字段如$schema、修剪过长的描述文本、扁平化一些简单的嵌套结构。通常能减少15%-20%的token且100%保持功能准确性。aggressive(激进)在标准基础上更进一步。它会移除那些从参数名就能明显推断出含义的描述例如path参数的描述是“The file path”并尝试合并重复出现的参数定义。这个级别开始对可读性有轻微影响但压缩率能提升到30%左右。extreme(极端) 和maximum(最大)这是slim-mcp的“杀手锏”也是实现70%以上压缩率的关键。它的核心思路非常巧妙既然LLM最终是通过阅读工具描述来理解如何调用那我们为什么不把最关键的类型签名直接“写进”描述里然后扔掉笨重的inputSchema呢举个例子一个原生的文件读取工具可能这样定义{ “name”: “read_file”, “description”: “Reads the contents of a file at the given path.”, “inputSchema”: { “type”: “object”, “properties”: { “path”: { “type”: “string”, “description”: “The path to the file.” } }, “required”: [“path”] } }经过extreme压缩后它可能变成{ “name”: “read_file”, “description”: “Reads the contents of a file. Args: path: string” }看到区别了吗完整的inputSchema被移除了参数的类型和必要性被浓缩成了一行类似TypeScript函数签名的文本附加在description末尾。LLM在解读description时自然就获取了调用所需的所有信息。maximum级别则更加极致会用‘s’代表string‘n’代表number‘!’标记必填参数变成“Args: path: s!”。重要提示这种“极端”压缩的有效性建立在LLM强大的自然语言理解能力上。项目作者进行了严谨的准确性测试后文会详述在120次API调用中达到了100%的准确率证实了这个假设在实践中是成立的。2.3 懒加载按需取用启动加速压缩解决的是“传输体积”问题懒加载解决的是“初始化负载”问题。想象一下一个GitHub MCP服务器可能提供了50个工具但你一次对话可能只用其中2-3个。为什么要在会话一开始就加载所有50个工具的完整定义呢slim-mcp的懒加载机制是这样的启动时它向所有后端服务器请求工具列表但只保留工具的name和一个极简的description例如“GitHub: List repositories”。这个“瘦身”列表被立即返回给客户端因此Agent能快速启动。首次调用时当Agent第一次尝试调用某个工具比如github__list_repos时slim-mcp会识别到这个工具只有“瘦身”定义。它会临时向对应的后端服务器请求该工具的完整Schema将其“提升”为完整工具然后重试这次调用。后续调用此后这个工具就有了完整定义可以直接使用。这个过程对AI Agent是完全透明的。用户只会感觉到第一次调用某个不常用的工具时可能有毫秒级的延迟但换来的是会话初始化速度的极大提升和初始上下文占用的大幅降低。官方数据是对于57个工具懒加载能将token从7702降至2722减少65%。2.4 响应缓存避免重复劳动很多MCP工具是“只读”的查询操作比如list_directory列出目录、search_code搜索代码。在短时间内重复查询相同的内容结果很可能是一样的。slim-mcp内置了一个智能缓存层。缓存键基于工具名和调用参数生成唯一键。缓存策略LRU最近最少使用算法防止缓存无限膨胀。生存时间可以为每个工具或全局设置TTL。例如文件列表缓存30秒代码搜索缓存5分钟。写操作失效这是关键。如果调用了write_file写文件或create_issue创建工单这类“写”操作slim-mcp会自动使相关路径或资源的缓存失效确保后续读操作能拿到最新数据。缓存命中能直接将响应速度提升到毫秒级并完全节省掉向后端服务器请求以及LLM生成响应内容的token消耗。3. 实战部署与多服务器集成理解了原理我们来看看如何把它用起来。slim-mcp提供了极大的灵活性支持单服务器包装、多服务器聚合、本地进程和远程HTTP连接等多种模式。3.1 基础安装与单服务器包装安装非常简单作为一个全局命令行工具即可npm install -g slim-mcp假设你现在想用Claude Code访问你的/tmp目录原本你的.mcp.json配置可能是直接调用文件系统服务器{ “mcpServers”: { “filesystem”: { “command”: “npx”, “args”: [“-y”, “modelcontextprotocol/server-filesystem”, “/tmp”] } } }现在你只需要在中间加上slim-mcp作为代理# 命令行直接测试 slim-mcp -- npx -y modelcontextprotocol/server-filesystem /tmp对应的.mcp.json配置变为{ “mcpServers”: { “filesystem”: { “command”: “npx”, “args”: [“-y”, “slim-mcp”, “--”, “npx”, “-y”, “modelcontextprotocol/server-filesystem”, “/tmp”] } } }注意--参数它用于分隔slim-mcp自身的选项和它要代理的实际命令。这样Claude Code连接的就是slim-mcp而slim-mcp在背后管理着文件系统服务器。你可以立即在Claude Code的工具列表里看到工具描述变得简洁了。3.2 多服务器集中管理推荐这是slim-mcp更强大的用法。你不再需要为每个MCP服务器在客户端配置里写一段command而是用一个配置文件统一管理。在项目根目录或家目录创建.slim-mcp.json{ “servers”: { “fs”: { “command”: “npx”, “args”: [“-y”, “modelcontextprotocol/server-filesystem”, “/tmp”], “always_load”: [“read_file”, “list_directory”], “cache_ttl”: 30 }, “gh”: { “command”: “npx”, “args”: [“-y”, “modelcontextprotocol/server-github”], “env”: { “GITHUB_PERSONAL_ACCESS_TOKEN”: “${GITHUB_TOKEN}” } }, “jira_cloud”: { “url”: “https://your-domain.atlassian.net/gateway/api/mcp”, “type”: “http”, “headers”: { “Authorization”: “Bearer ${JIRA_TOKEN}” } } }, “compression”: “extreme”, “dashboard”: { “enabled”: true, “port”: 7333 } }这个配置定义了三个服务器本地文件系统服务器使用always_load强制预加载read_file和list_directory这两个常用工具避免首次调用的延迟。并设置缓存TTL为30秒。本地GitHub服务器通过环境变量传入Token。${GITHUB_TOKEN}会在运行时从你的系统环境变量中读取。远程Jira HTTP服务器这展示了slim-mcp可以代理远程HTTP/SSE类型的MCP服务无需在本地运行进程。然后你的客户端配置如Claude Code的.mcp.json就变得极其简洁{ “mcpServers”: { “my_slim_proxy”: { “command”: “npx”, “args”: [“-y”, “slim-mcp”, “--config”, “/path/to/your/.slim-mcp.json”] } } }客户端只需要连接slim-mcp这一个入口。slim-mcp会聚合fs、gh、jira_cloud的所有工具并在工具名前加上服务器名作为命名空间例如fs__read_filegh__search_issues避免名称冲突。启动时直接运行slim-mcp它会自动发现并使用当前目录下的.slim-mcp.json配置文件。实操心得环境变量管理在配置文件中使用${VAR}语法是个好习惯。这意味着你的敏感Token不会硬编码在配置文件中。你只需要在启动终端前设置好这些环境变量比如在.zshrc或.bashrc中export或使用direnv等工具slim-mcp会自动注入。这比在多个客户端配置里重复写Token要安全、方便得多。3.3 实时监控仪表盘当以多服务器模式运行时强烈建议启用内置的Web仪表盘。只需在配置中设置“dashboard”: {“enabled”: true}或启动时加上--dashboard-port 7333。访问http://localhost:7333你会看到一个实时的监控界面。它能展示总体节省对比原始和压缩后的总Token消耗直观看到节省了多少上下文空间。服务器状态每个后端服务器的运行状态健康/异常。缓存命中率全局和每个工具的缓存命中情况帮你判断缓存配置是否合理。工具调用流水最近调用的工具列表显示是缓存命中HIT、缓存未命中MISS还是懒加载提升PROMOTED以及响应时间。这个仪表盘通过Server-Sent Events实时更新对于调试和观察系统行为非常有帮助。你能亲眼看到懒加载何时触发、缓存如何生效从而更好地调整always_load列表和cache_ttl参数。4. 高级配置与性能调优指南slim-mcp提供了丰富的配置选项让你能根据实际工作流进行精细调优。4.1 缓存策略深度配置缓存是性能提升的关键但也需要合理配置以避免数据过时。{ “cache”: { “default_ttl”: 60, // 默认缓存60秒 “max_entries”: 1000, // 最多缓存1000个条目防止内存溢出 “never_cache”: [“write_to_database”, “send_notification”], // 永远不缓存这些“写”工具 “servers”: { “fs”: { “tools”: { “list_directory”: { “ttl”: 30 }, // 文件列表缓存30秒 “search_files”: { “ttl”: 300 } // 文件搜索缓存5分钟 } } } } }never_cache这是最重要的安全配置。务必把所有会产生副作用的工具创建、更新、删除、发送列在这里确保缓存不会导致重复操作或数据不一致。分层TTL像list_directory这种变化相对频繁的操作TTL可以设短一点如10-30秒。而像search_files这种开销大、结果相对稳定的查询TTL可以设长一些如300秒。监控调整结合仪表盘的缓存命中率数据来调整。如果某个工具缓存命中率极低说明它的参数变化多端或TTL太短可以考虑将其移出缓存或缩短TTL。4.2 懒加载与预加载平衡懒加载虽好但首次调用延迟会影响体验。你需要决定哪些工具值得“预加载”。{ “servers”: { “fs”: { “command”: “...”, “always_load”: [“read_file”, “list_directory”] // 预加载这两个最常用工具 }, “gh”: { “command”: “...”, “lazy_threshold”: 5 // 当此服务器的工具数超过5个时才启用懒加载 } }, “max_tools_loaded”: 15 // 全局限制最多同时保留15个工具的完整Schema }always_load把你工作流中每次会话几乎必用的工具放这里。比如对于代码编辑read_file和list_directory就是典型候选。lazy_threshold如果一个服务器本身工具就不多比如少于5个懒加载的收益可能抵不上其复杂性可以直接关闭全部预加载。max_tools_loaded这是一个全局的内存/性能保护阀。slim-mcp会使用LRU策略当缓存的完整工具数超过这个限制时最久未使用的工具定义会被“降级”回瘦身版本。根据你的系统内存和工具数量调整此值。4.3 压缩等级选择实践选择哪个压缩等级取决于你的LLM和你的容忍度。Claude Sonnet/Opus经过测试即使使用maximum压缩也能保持100%准确率。你可以放心使用最高级别获得最大token节省。其他LLM如果你使用的是其他可能对指令跟随能力稍弱的模型建议从aggressive级别开始测试。观察工具调用是否准确再决定是否升级到extreme。调试阶段在集成和调试初期可以暂时使用standard甚至none级别确保所有工具都能被正常发现和调用。稳定后再逐步提高压缩等级。你可以在命令行快速测试不同级别的效果slim-mcp --compression aggressive -- npx -y modelcontextprotocol/server-filesystem /tmp5. 故障排查与常见问题实录在实际集成和使用过程中我遇到了一些典型问题这里记录下排查思路和解决方案。5.1 工具调用失败或参数错误现象AI Agent列出了工具但调用时失败或参数似乎传递不正确。检查压缩等级这是最常见的原因。如果你从none切换到了extreme而LLM无法正确解析嵌入在描述中的类型签名就会出错。临时解决方案将compression级别降回aggressive或standard测试是否恢复正常。长期排查运行项目自带的准确性测试脚本需要Anthropic API Key验证你的LLM模型在当前压缩级别下的准确性。检查懒加载状态在仪表盘中查看该工具调用是否是PROMOTED。如果是说明这是首次调用延迟和失败可能是后端服务器本身的问题或网络问题。检查slim-mcp进程的stderr输出看是否有来自后端服务器的错误信息。验证原始服务器绕过slim-mcp直接用原始命令启动MCP服务器并用mcp-cli或客户端测试工具调用是否正常。确保问题不是出在底层服务器上。5.2 仪表盘无法访问或服务器状态异常现象访问http://localhost:7333无响应或仪表盘上某个服务器显示为离线。检查端口占用7333端口可能被其他程序占用。可以通过--dashboard-port 8080指定另一个端口。检查服务器配置确认.slim-mcp.json中每个服务器的command或url配置正确。对于command确保该命令可以在你的终端环境中直接运行。对于url尝试用curl命令测试该端点是否可达。查看日志输出运行slim-mcp时添加-v或--verbose标志。这会在控制台打印所有MCP协议层的JSON-RPC消息对于诊断连接和初始化问题至关重要。你会看到slim-mcp与每个后端服务器的握手initialize过程是否成功。5.3 缓存导致的数据过时问题现象文件明明被修改了但Agent通过read_file读到的还是旧内容。确认缓存配置检查该工具的cache_ttl设置。可能是TTL设置过长。检查写操作失效确保修改文件的操作无论是通过另一个MCP工具还是外部程序触发了缓存失效。slim-mcp主要依赖来自同一服务器的“写工具”调用如write_file来失效缓存。如果你是通过外部编辑器修改文件slim-mcp无从知晓。解决方案对于这种场景可以适当缩短该工具如read_file的缓存TTL或者将其从缓存中排除never_cache。手动清除缓存目前slim-mcp没有提供手动清除缓存的管理命令。如果遇到紧急的数据不一致情况最直接的方法是重启slim-mcp进程缓存会全部清空。5.4 与特定客户端Cursor, Windsurf的集成问题现象在Claude Code中工作正常但在Cursor或Windsurf中无法连接或工具不显示。确认传输协议确保你的slim-mcp配置和启动方式与客户端期望的匹配。大多数客户端期望通过stdio与MCP服务器通信。你的slim-mcp配置必须是command模式并且整个命令链能正常启动。检查客户端配置路径Cursor和Windsurf通常有自己指定的MCP配置文件路径如~/.cursor/mcp.json或~/.windsurf/mcp.json。确保你修改的是正确的配置文件。权限与环境当通过GUI应用如Cursor启动时其进程可能运行在不同的用户环境或受限环境中可能读取不到你终端里设置的环境变量如GITHUB_TOKEN。尝试在slim-mcp的配置文件中直接写入绝对路径的Token仅限测试注意安全或查阅客户端的文档看如何为其设置全局环境变量。5.5 性能问题启动慢或调用延迟高现象启动AI Agent时加载工具列表很慢或调用工具时响应迟缓。分析瓶颈使用--verbose模式启动观察延迟发生在哪个阶段。是在slim-mcp初始化所有后端服务器时还是在懒加载提升某个工具时还是在缓存未命中后的实际工具执行时优化服务器启动如果后端服务器本身启动慢例如某些需要连接数据库的服务器这个延迟是无法通过slim-mcp消除的。考虑是否为这些服务器配置always_load让它们在slim-mcp启动时即并行初始化而不是等到第一次调用。调整懒加载阈值如果工具总数不多例如小于10个禁用懒加载--no-lazy可能反而更快因为避免了首次调用的“提升-重试”开销。检查网络如果使用了远程HTTP服务器url延迟可能来自网络。考虑优化网络连接或将服务器部署在更近的位置。6. 项目开发与贡献指南slim-mcp本身是一个Node.js项目架构清晰。如果你对其原理感兴趣或想为其添加新功能如支持新的压缩算法、更细粒度的缓存策略可以参与到项目中。6.1 项目结构与核心模块src/ ├── index.ts # CLI入口点 ├── proxy/ # 代理核心逻辑 │ ├── McpProxy.ts # 主代理类管理服务器和生命周期 │ ├── SchemaCompressor.ts # 压缩策略实现核心 │ ├── LazyLoader.ts # 懒加载逻辑 │ └── ResponseCache.ts # 缓存管理 ├── transport/ # 传输层 │ ├── StdioTransport.ts # 本地进程通信 │ └── HttpTransport.ts # 远程HTTP/SSE通信 ├── dashboard/ # 监控仪表盘前端SSE后端 └── types.ts # 类型定义SchemaCompressor.ts这是实现token压缩的核心。五个压缩等级none到maximum在这里被具体实现为一系列转换函数。如果你想实验一种新的压缩格式这是主要的修改点。LazyLoader.ts管理工具的“瘦身”索引和“提升”逻辑。它维护了一个工具状态映射。ResponseCache.ts基于工具名和参数哈希的缓存系统实现了TTL和LRU失效。6.2 运行测试套件项目拥有完善的测试体系确保修改不会破坏现有功能。# 安装依赖 npm install # 运行单元测试快速反馈 npm test # 运行端到端集成测试需要启动本地测试服务器 npm run test:e2e # 运行“冒烟测试”针对你本地已配置的真实MCP服务器进行测试 # 这会读取你的 ~/.claude.json 等配置实际调用工具 npm run smoke-test最重要的准确性测试这个测试直接调用Anthropic API验证压缩后的工具描述是否会被LLM误解。ANTHROPIC_API_KEYsk-your-key-here npx tsx scripts/accuracy-test.ts你需要准备一个Anthropic API Key。测试会遍历所有压缩等级模拟大量工具调用场景并断言结果正确。这是保证slim-mcp核心价值压缩不减效的基石任何对压缩逻辑的修改都必须通过此测试。6.3 可能的扩展方向自适应压缩目前的压缩等级是全局设置的。一个更智能的方案是根据工具的使用频率或复杂度动态选择压缩等级。高频复杂工具用standard保证可读性低频简单工具用maximum极致压缩。缓存持久化将缓存存储到磁盘如SQLite这样即使重启slim-mcp进程热点数据的缓存依然有效能实现“冷启动”加速。更智能的缓存失效目前主要依赖“写工具”调用进行失效。可以探索基于文件系统监听inotify/fsevents或数据库触发器等方式实现更精确的自动失效。协议扩展支持随着MCP协议本身演进如支持流式响应、工具调用反馈slim-mcp需要同步更新以透明地支持这些新特性。这个项目的价值在于它精准地切中了AI Agent工具化实践中的一个痛点。随着我们赋予Agent的能力越来越强集成的工具越来越多如何高效地管理这些工具的“元信息”本身就成了一个需要被工具化解决的问题。slim-mcp提供了一个优雅且经过实战检验的解决方案它让我能在Claude Code中同时挂载十多个MCP服务器而无需担心上下文被撑爆真正实现了“工具自由”。