MCP服务器技能
模型上下文协议(MCP)服务器从本地目录提供专门的提示库(技能),并提供 懒惰MCP桥 为了与分层工具系统兼容。为任何兼容MCP的客户端提供跨域专家知识的令牌高效访问。
> 平台兼容性:此服务器已 在Linux上测试和开发,但应在配置正确的macOS和Windows上运行。核心技能功能适用于所有平台,而Lazy MCP Bridge集成需要特定于平台的配置调整。有关特定于平台的详细说明,请参阅 安装.md.
特性
- 渐进呈现:只有上下文中的技能元数据(约50个令牌/技能),按需加载完整内容
- 代币高效:工具发现期间令牌使用量减少95%以上
- 自动发现:从可配置目录自动扫描和加载技能
- 热重新加载:技能立即更新,无需重新启动服务器
- 可配置的:环境变量控制技能目录位置
- 懒惰MCP桥:通过渐进式披露无缝集成懒惰的mcp分层工具(最初只公开了2个导航工具)
- 通用:适用于任何MCP客户端(Cline和其他CLI工具)
- 技能验证:强制执行命名约定和内容规则
- 可执行技能:通过工具编排动态生成指令
- 动态行为:具有参数支持的上下文感知技能执行
- 工具编排:技能可以指定和使用可用的工具
安装
有关Windows、macOS和Linux的详细安装说明,请参阅 安装.md.
快速开始
- 先决条件:Node.js 18+、npm或yarn。
- 全球安装 (推荐):```bash
npm install -g @skills-server/mcp
这将安装 `skills-server` 全球指挥。
1. **地方发展**:```bash
git clone https://github.com/ivanenev/skills-server.git
cd skills-server
npm install
npm run build
后续步骤
- 配置环境变量(请参见 配置.md).
- 设置技能目录(默认
~/.skills). - 与您的MCP客户端(Cline和其他CLI工具)集成。
有关故障排除,请参阅 故障排除.md.
配置
有关详细的配置选项、环境变量和路径自定义,请参阅 配置.md.
快速参考
- 技能目录:设置
SKILLS_DIR环境变量(默认值:~/.skills). - 延迟MCP集成:启用
LAZY_MCP_ENABLED=true并设置LAZY_MCP_COMMAND到你懒惰的mcp可执行文件。 - 缓存持续时间:控制
CACHE_DURATION(默认值:5000毫秒)。
MCP客户端设置
将服务器添加到MCP客户端配置中。MCP客户端示例:```json
{
"mcpServers": {
"skills-server": {
"command": "skills-server",
"env": {
"SKILLS_DIR": "~/.skills",
"LAZY_MCP_ENABLED": "true"
}
}
}
}
对于其他客户(Cline等),请参阅 配置.md.
## 懒惰MCP桥(不需要,但建议)
服务器与 **懒惰的mcp** 通过 VoiceTreeLab 以提供对分层工具系统的访问。此桥实现了传统MCP工具和懒惰MCP的分层架构之间的无缝兼容性。
### 安装懒惰MCP
**先决条件:**
- Python 3.8+
- pip包管理器
**安装:**```bash
# Clone the repository
git clone https://github.com/voicetreelab/lazy-mcp.git
cd lazy-mcp
# Install dependencies
pip install -r requirements.txt
# Make the run script executable
chmod +x run-lazy-mcp.sh
配置:
当惰性mcp在您的系统PATH中可用时,或者当 LAZY_MCP_COMMAND 环境变量指向懒惰的mcp可执行文件。
桥梁特征
启用后,服务器会自动:
- 渐进呈现:仅显示两个导航工具(
lazy_mcp_get_tools_in_category和lazy_mcp_execute_tool)而不是将所有143+个工具压平。 - 代币效率:保留懒惰mcp的分层令牌节省(约500个令牌,而完整工具列表为25000多个)。
- 无缝集成:不需要对现有的懒惰mcp设置进行更改。
- 差错恢复:如果懒惰的mcp不可用,请进行优雅的回退。
桥梁优势
- 通用访问:所有懒惰的mcp工具都可以通过渐进式导航在任何mcp客户端中使用。
- 代币节省:分层加载,无需客户端更改。
- 向后兼容:与希望直接访问工具的MCP客户端配合使用。
- 保留的层次结构:维护懒人mcp的组织结构。
定制
用户重要提示
此软件包包括一个针对作者环境优化的预配置懒惰mcp设置。 为了获得完整的体验,您需要为自己的设置自定义技能服务器和懒惰的mcp配置。
1.自定义工具类别
技能服务器过滤懒惰的mcp工具,以防止与VS Code扩展内部工具的重复。要自定义包含哪些类别,请执行以下操作:
编辑 src/index.ts (第239-243行):```typescript
const universalCategories = [
'brave-search', 'playwright', 'puppeteer', 'filesystem',
'desktop-commander', 'memory', 'youtube', 'fuse-optimizer',
'brave-search-marketplace', 'playwright-marketplace', 'puppeteer-marketplace', 'whatsapp-mcp'
];
**修改此数组以包含与可用MCP服务器匹配的类别。**
### 2.设置自己的懒惰MCP
您的懒惰mcp配置需要指向您自己的mcp服务器位置:
1. **安装懒惰mcp** 跟随 官方文档
1. **配置您的MCP服务器** 在懒惰的麦当劳 `config.json`
1. **更新服务器路径** 以匹配您的安装位置
1. **重新生成层次结构** 使用lazy mcp的结构生成器
### 3.部署注意事项
- **核心技能功能** 没有懒惰的mcp也能工作。
- **懒惰的mcp集成** 需要您自己的懒惰mcp设置。
- **工具过滤** 防止与VS Code扩展内部工具发生冲突。
- **需要定制** 在您的环境中实现最佳性能。
## 技能格式
每个技能都是一个目录,其中包含 `SKILL.md` 带有YAML frontmatter的文件:```
skill-name/
└── SKILL.md
SKILL.md结构```markdown
name: skill-name
description: Brief description of what this skill does and when to use it
type: static | executable # Optional: defines skill behavior
allowed_tools: [tool1, tool2] # Optional: tools this skill can orchestrate
execution_logic: conditional # Optional: dynamic behavior type
parameters: # Optional: skill parameters
param1: string
param2: object
Skill Title
[Comprehensive skill content with instructions, examples, and best practices]
### 示例技能
**静态技能(传统):**```markdown
---
name: docker-compose-manager
description: Manages Docker Compose services for containerized applications. Use when starting, stopping, or checking status of Docker services.
---
# Docker Compose Manager Skill
You are an expert at managing Docker Compose services...
## Core Operations
- **Start services**: Use `docker-compose up -d`
- **Stop services**: Use `docker-compose down`
- etc.
可执行技能(高级):```markdown
name: debug-agent
description: Dynamic debugging agent that analyzes errors and provides fixes using available tools
type: executable
allowed_tools: [list_directory, read_file, search_files, system-monitoring]
execution_logic: conditional
parameters:
error_type: string
context: object
Debug Agent - Dynamic Problem Solver
You are an expert debugging agent that can analyze problems and provide solutions using available tools...
Dynamic Decision Making
Based on the error type and context, select the appropriate tools and approach:
- File-related issues: Use file system tools to examine code and configuration
- System problems: Use monitoring tools to check health and performance
- Integration errors: Test connectivity and data flow
- Logic errors: Analyze code and test different scenarios
Always provide clear explanations of your findings and step-by-step solutions.
## 用法
### 使用像Cline这样的VS代码扩展
配置后,技能和懒惰的mcp工具将通过渐进式披露自动可用:```
You: "Search for React component libraries"
Cline: [Uses lazy_mcp_get_tools_in_category to find brave-search category,
then lazy_mcp_execute_tool with tool_path "brave-search.brave_web_search"]
You: "Navigate to example.com and take a screenshot"
Cline: [Uses lazy_mcp_execute_tool with tool_path "playwright.browser_navigate",
then lazy_mcp_execute_tool with tool_path "playwright.browser_take_screenshot"]
You: "Set up PostgreSQL database connection"
Cline: [Loads postgres skill automatically]
与其他MCP客户端
技能和懒惰的mcp工具作为标准的mcp工具出现。 注: 与Claude Code和其他CLI工具的集成尚未经过测试,但应基于MCP协议兼容性。
渐进式披露架构
运作原理
- 发现:服务器扫描
SKILLS_DIR技能目录。 - 元数据加载:只读取用于工具发现的YAML frontmatter(名称、描述)。
- 工具注册:创建仅包含元数据信息的MCP工具。
- 延迟MCP集成:启用后,仅显示两个导航工具(
lazy_mcp_get_tools_in_category和lazy_mcp_execute_tool)而不是将所有143+个工具压平。 - 渐进式加载:仅在浏览类别时加载完整的工具详细信息;仅在实际调用技能时加载完整的技能内容。
- 代币效率:在发现过程中,每项技能约50个代币,而完整内容则有1500多个代币;懒惰mcp导航约500个代币,而完整工具列表则超过25000个代币。
经验证的绩效指标
- JSON响应大小:减少54%(91KB→ 42KB)
- 代币效率:工具发现期间减少95%以上
- 延迟MCP代币节省:减少92.1%(7298个代币→ 574 代币)通过以下方式测量
measure-progressive-tokens.js - 技能代币储蓄:减少96.5%(12328个代币→ 430 代币)通过以下方式测量
measure-progressive-tokens.js - 渐进式披露修复:修复前:约30000个代币,修复后:574个代币,节省:减少98.1%
- 理论最大值:全工具上市约25000多个代币,而渐进披露约500个代币
- 工具发现:每项技能约50个令牌(仅元数据)
- 技能执行:仅在需要时提供完整内容(1500+代币)
- 内容扩展:发现和执行之间的内容比率为22倍
- 真实AI验证:渐进式披露适用于技能和懒惰的mcp工具
- 可执行技能:动态指令生成,节省89.2%的令牌
- 工具编排:技能可以动态使用可用的MCP工具
缓存
- 元数据缓存:技能元数据为5秒
- 完整内容缓存:30秒完成技能内容
- 热重新加载:无需重新启动服务器即可立即反映更改
发展
项目结构```
skills-server/
├── src/
│ └── index.ts # Main server implementation
├── build/
│ └── index.js # Compiled server
├── package.json
└── README.md
### 添加功能
服务器可以通过以下方式进行扩展:
- 附加技能元数据
- 技能验证
- 自定义技能格式
- 与外部API集成
### 测试```bash
# Build and test
npm run build
npm test
# Run comprehensive test suite
node test_runner.js
# Validate progressive disclosure
node test-progressive-disclosure.js
# Measure token savings
node measure-progressive-tokens.js
渐进式披露验证
服务器包括全面的测试,用于验证:
- 代币效率:发现令牌减少95%以上
- 仅元数据发现:在工具列表中仅显示技能名称/描述
- 完整内容加载:调用工具时完成技能内容
- 技能验证:正确的命名约定和内容规则
- 真正的AI集成:已准备好与实际型号一起投入生产使用
api参考
工具
- 获取技能:返回所请求技能的全部内容
- 输入:
skill_name(字符串) - 输出:完成技能标记内容
- lazy_mcp_get_tools_incategory:浏览懒惰mcp工具层次结构
- 输入:
path(string)-使用点表示法的类别路径(根为空字符串) - 输出:JSON结构,在该路径上有子类别和工具
- lazy_mcpexecute_tool:按层次路径执行懒惰mcp工具
- 输入:
tool_path(字符串),arguments(对象) - 输出:工具执行结果
配置选项
SKILLS_DIR:包含技能文件夹的目录CACHE_DURATION:技能缓存持续时间(毫秒)(默认值:5000)LAZY_MCP_ENABLED:启用延迟mcp集成(默认值:false)LAZY_MCP_COMMAND:懒惰mcp可执行文件的路径
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用,添加测试
- 提交拉取请求
许可证
GPL-3.0许可证-有关详细信息,请参阅许可证文件。
相关项目
- MCP协议 -模型上下文协议规范
内置于 模型上下文协议SDK