staff-mcp 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +86 -43
  2. package/README_zh.md +84 -43
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -2,44 +2,42 @@
2
2
 
3
3
  [English](./README.md) | [简体中文](./README_zh.md)
4
4
 
5
- A powerful Model Context Protocol (MCP) server providing file management, shell execution, and LSP capabilities. Built for seamless integration with AI assistants like Claude Desktop, IDE plugins, and custom agents.
5
+ A robust Model Context Protocol (MCP) server that provides AI assistants with a secure, cross-platform environment for file management, shell execution, and LSP-powered code intelligence.
6
6
 
7
- ## 🚀 Quick Start
7
+ ---
8
8
 
9
- ### Installation
9
+ ## 🚀 Usage
10
10
 
11
- ```bash
12
- npm install
13
- npm run build
14
- ```
11
+ Use this section if you want to run the published package.
15
12
 
16
- ### Running the Server
13
+ ### Run with npx
17
14
 
18
- **Using npx (Quickest)**
15
+ Recommended command:
19
16
 
20
17
  ```bash
21
- # From local directory
22
- npx . --working-dir /path/to/your/project
23
-
24
- # If published to npm (e.g., @your-org/staff-mcp)
25
- # npx -y @your-org/staff-mcp --working-dir /path/to/your/project
18
+ npx -y staff-mcp@latest --working-dir /path/to/your/project
26
19
  ```
27
20
 
28
- **Stdio Mode (Recommended for Claude Desktop)**
29
-
30
- ```bash
31
- # Using npm (Recommended)
32
- npm start -- --working-dir /path/to/your/project
33
- ```
34
-
35
- **HTTP Mode**
36
-
37
- ```bash
38
- # Using npm
39
- npm start -- --transport http --port 3000
40
-
41
- # Using node directly
42
- node dist/src/index.js --transport http --port 3000
21
+ Using `@latest` is the safest option for a published CLI package and avoids resolution issues such as `could not determine executable to run`.
22
+
23
+ ### Configure for Claude Desktop
24
+
25
+ Add the following to your `claude_desktop_config.json`:
26
+
27
+ ```json
28
+ {
29
+ "mcpServers": {
30
+ "staff-mcp": {
31
+ "command": "npx",
32
+ "args": [
33
+ "-y",
34
+ "staff-mcp@latest",
35
+ "--working-dir",
36
+ "/path/to/your/project"
37
+ ]
38
+ }
39
+ }
40
+ }
43
41
  ```
44
42
 
45
43
  ### CLI Arguments
@@ -49,41 +47,86 @@ node dist/src/index.js --transport http --port 3000
49
47
  | `--working-dir` | Root directory for the sandbox | `process.cwd()` |
50
48
  | `--allowed-dir` | Extra directories allowed for access | `[]` |
51
49
  | `--transport` | Transport type (`stdio` or `http`) | `stdio` |
52
- | `--port` | Port for HTTP server | `3000` |
50
+ | `--port` | Port for HTTP server (if using http) | `3000` |
51
+
52
+ ### Skill Loading
53
+
54
+ `staff-mcp` can work with skill directories if they already exist in your workspace or home directory. To use them, place skill files in any supported location such as:
55
+
56
+ - `.staff/skills/<skill-name>/SKILL.md`
57
+ - `.claude/skills/<skill-name>/SKILL.md`
58
+ - `.agents/skills/<skill-name>/SKILL.md`
59
+ - `.opencode/skills/<skill-name>/SKILL.md`
60
+
61
+ The server discovers them automatically at startup.
53
62
 
54
63
  ---
55
64
 
56
- ## 🛠️ Supported MCP Features
65
+ ## 🛠️ Core Features
66
+
67
+ - **File Operations**: Secure read, write, delete, and list operations within the sandbox.
68
+ - **Shell Integration**: Execute non-interactive commands or start background tasks (e.g., dev servers).
69
+ - **Code Intelligence**: LSP-based symbol extraction and diagnostics for better code understanding.
70
+ - **Skill System**: Automatically detects and loads domain-specific instructions from `.staff/skills/`, `.claude/skills/`, and `.agents/skills/`.
71
+ - **Environment Awareness**: Native support for Windows (CMD/PowerShell) and Unix-like (Bash/Sh) systems.
57
72
 
58
- - **Tools**: Comprehensive file operations, shell execution, and LSP support.
59
- - **Skills & Prompts**: Compatible with the `SKILL.md` format. Automatically detects skills in `.staff/skills/`, `.claude/skills/`, etc.
60
- - **MCP Native Support**: Implements the `instructions` mechanism to provide model context for environment awareness (OS, shell, etc.) and tool relationships.
73
+ ### Adding Skills
61
74
 
62
- ### Skill File Format (`SKILL.md`)
75
+ Create a `SKILL.md` file in `.staff/skills/your-skill/`:
63
76
 
64
77
  ```markdown
65
78
  ---
66
79
  name: my-skill
67
- description: Skill description
80
+ description: Custom logic for my project
68
81
  ---
69
- Skill instructions here...
82
+ Add your domain-specific instructions or workflows here.
70
83
  ```
71
84
 
72
85
  ---
73
86
 
74
- ## 💻 Cross-Platform Compatibility
87
+ ## 🧪 Development
75
88
 
76
- `staff-mcp` handles environment differences automatically:
77
- - **Paths**: Resolves `\` (Windows) and `/` (Unix) based on host OS.
78
- - **Shell**: Uses `cmd.exe` on Windows and `sh` on Linux/macOS.
79
- - **Line Endings**: Supports both `CRLF` and `LF` for file operations.
89
+ Use this section only if you want to work on the repository itself.
80
90
 
81
- ## 🧪 Development
91
+ ### Local setup
82
92
 
83
93
  ```bash
94
+ git clone https://github.com/your-username/staff-mcp.git
95
+ cd staff-mcp
96
+ npm install
97
+ npm run build
98
+ ```
99
+
100
+ ### Run the local build
101
+
102
+ ```bash
103
+ node dist/src/index.js --working-dir ./test-workspace
104
+ ```
105
+
106
+ ### Run with npm scripts
107
+
108
+ ```bash
109
+ npm start -- --working-dir ./test-workspace
84
110
  npm run dev -- --working-dir ./test-workspace
85
111
  ```
86
112
 
113
+ ## ✅ Testing
114
+
115
+ Examples for verifying the package behavior separately from normal usage:
116
+
117
+ ### Verify the published package
118
+
119
+ ```bash
120
+ npx -y staff-mcp@latest --working-dir /tmp
121
+ ```
122
+
123
+ ### Verify the local build
124
+
125
+ ```bash
126
+ npm run build
127
+ node dist/src/index.js --working-dir /tmp
128
+ ```
129
+
87
130
  ## 📄 License
88
131
 
89
132
  MIT
package/README_zh.md CHANGED
@@ -2,44 +2,42 @@
2
2
 
3
3
  [English](./README.md) | [简体中文](./README_zh.md)
4
4
 
5
- 一个功能强大的 Model Context Protocol (MCP) 服务端，提供文件管理、Shell 执行和 LSP 能力。专为 AI 助手（如 Claude Desktop、IDE 插件和自定义 Agent）的无缝集成而设计。
5
+ 一个稳健的 Model Context Protocol (MCP) 服务端，为 AI 助手提供安全、跨平台的文件管理、Shell 执行和基于 LSP 的代码智能环境。
6
6
 
7
- ## 🚀 快速开始
8
-
9
- ### 安装
10
-
11
- ```bash
12
- npm install
13
- npm run build
14
- ```
7
+ ---
15
8
 
16
- ### 运行服务
9
+ ## 🚀 使用
17
10
 
18
- **使用 npx (最快方式)**
11
+ 这一节用于说明如何直接使用已发布的包，而不是如何开发或测试这个仓库。
19
12
 
20
- ```bash
21
- # 在项目本地运行
22
- npx . --working-dir /你的项目/路径
23
-
24
- # 如果已发布到 npm (例如 @your-org/staff-mcp)
25
- # npx -y @your-org/staff-mcp --working-dir /你的项目/路径
26
- ```
13
+ ### 使用 npx 运行
27
14
 
28
- **Stdio 模式 (Claude Desktop 推荐方式)**
15
+ 推荐命令：
29
16
 
30
17
  ```bash
31
- # 使用 npm (推荐)
32
- npm start -- --working-dir /你的项目/路径
18
+ npx -y staff-mcp@latest --working-dir /你的项目/路径
33
19
  ```
34
20
 
35
- **HTTP 模式**
36
-
37
- ```bash
38
- # 使用 npm
39
- npm start -- --transport http --port 3000
40
-
41
- # 使用 node 直接启动
42
- node dist/src/index.js --transport http --port 3000
21
+ 对于已发布的 CLI 包，显式使用 `@latest` 更稳妥，也可以避免类似 `could not determine executable to run` 的解析问题。
22
+
23
+ ### 在 Claude Desktop 中配置
24
+
25
+ 将以下内容添加到你的 `claude_desktop_config.json` 文件中：
26
+
27
+ ```json
28
+ {
29
+ "mcpServers": {
30
+ "staff-mcp": {
31
+ "command": "npx",
32
+ "args": [
33
+ "-y",
34
+ "staff-mcp@latest",
35
+ "--working-dir",
36
+ "/你的项目/路径"
37
+ ]
38
+ }
39
+ }
40
+ }
43
41
  ```
44
42
 
45
43
  ### 命令行参数
@@ -49,41 +47,84 @@ node dist/src/index.js --transport http --port 3000
49
47
  | `--working-dir` | 沙箱根目录 | `process.cwd()` |
50
48
  | `--allowed-dir` | 额外允许访问的目录 | `[]` |
51
49
  | `--transport` | 传输方式 (`stdio` 或 `http`) | `stdio` |
52
- | `--port` | HTTP 服务端口 | `3000` |
50
+ | `--port` | HTTP 服务端口 (如果使用 http 模式) | `3000` |
51
+
52
+ ### Skill 加载方式
53
+
54
+ 如果你的工作区或用户目录里已经存在 skill 目录，`staff-mcp` 会在启动时自动发现并加载。可用目录示例：
55
+
56
+ - `.staff/skills/<skill-name>/SKILL.md`
57
+ - `.claude/skills/<skill-name>/SKILL.md`
58
+ - `.agents/skills/<skill-name>/SKILL.md`
59
+ - `.opencode/skills/<skill-name>/SKILL.md`
53
60
 
54
61
  ---
55
62
 
56
- ## 🛠️ 支持的 MCP 特性
63
+ ## 🛠️ 核心特性
64
+
65
+ - **文件操作**: 在沙箱范围内提供安全的读、写、删除和列表操作。
66
+ - **Shell 集成**: 执行非交互式命令或启动后台任务（如开发服务器）。
67
+ - **代码智能**: 基于 LSP 的符号提取和诊断，帮助 AI 更好地理解代码结构。
68
+ - **技能系统 (Skills)**: 自动检测并加载 `.staff/skills/`、`.claude/skills/` 和 `.agents/skills/` 目录下的领域特定指令。
69
+ - **环境感知**: 原生支持 Windows (CMD/PowerShell) 和 Unix-like (Bash/Sh) 系统。
57
70
 
58
- - **Tools (工具)**: 提供完整的文件操作、Shell 执行和 LSP（符号/诊断）支持。
59
- - **Skills (技能)**: 兼容 `SKILL.md` 格式。自动检测并注册 `.staff/skills/`、`.claude/skills/` 等目录下的技能及 Prompts。
60
- - **MCP 原生支持**: 实现了 `instructions` 机制，为模型自动提供环境感知（OS、Shell、路径规则）及工具调用建议。
71
+ ### 如何添加技能
61
72
 
62
- ### Skill 文件格式 (`SKILL.md`)
73
+ 在 `.staff/skills/your-skill/` 目录下创建一个 `SKILL.md` 文件：
63
74
 
64
75
  ```markdown
65
76
  ---
66
77
  name: my-skill
67
- description: 技能描述
78
+ description: 我的项目专属逻辑
68
79
  ---
69
- 这里是技能的具体指令...
80
+ 在此处添加你的领域特定指令或工作流。
70
81
  ```
71
82
 
72
83
  ---
73
84
 
74
- ## 💻 跨平台兼容性
85
+ ## 🧪 开发
75
86
 
76
- `staff-mcp` 自动处理环境差异：
77
- - **路径**: 根据宿主系统解析 `\` (Windows) 或 `/` (Unix)。
78
- - **Shell**: Windows 使用 `cmd.exe`，Linux/macOS 使用 `sh`。
79
- - **换行符**: 文件操作支持 `CRLF` 和 `LF`。
87
+ 这一节只面向要修改仓库源码的开发者。
80
88
 
81
- ## 🧪 开发
89
+ ### 本地准备
90
+
91
+ ```bash
92
+ git clone https://github.com/your-username/staff-mcp.git
93
+ cd staff-mcp
94
+ npm install
95
+ npm run build
96
+ ```
97
+
98
+ ### 运行本地构建产物
82
99
 
83
100
  ```bash
101
+ node dist/src/index.js --working-dir ./test-workspace
102
+ ```
103
+
104
+ ### 使用 npm 脚本运行
105
+
106
+ ```bash
107
+ npm start -- --working-dir ./test-workspace
84
108
  npm run dev -- --working-dir ./test-workspace
85
109
  ```
86
110
 
111
+ ## ✅ 测试
112
+
113
+ 这一节单独用于说明如何验证包是否可用，而不是日常使用方式。
114
+
115
+ ### 验证已发布包
116
+
117
+ ```bash
118
+ npx -y staff-mcp@latest --working-dir /tmp
119
+ ```
120
+
121
+ ### 验证本地构建
122
+
123
+ ```bash
124
+ npm run build
125
+ node dist/src/index.js --working-dir /tmp
126
+ ```
127
+
87
128
  ## 📄 开源协议
88
129
 
89
130
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "staff-mcp",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "type": "module",
5
5
  "main": "dist/src/index.js",
6
6
  "bin": {