Skip to content

Commit a5fd2d8

Browse files
DeadWaveWaveDeadWaveWave
committed
feat: update README and usage documentation for MCP client configuration
- Added detailed instructions for configuring MCP clients (Cursor and Kiro) to use WaveForge via npx. - Included JSON and TOML configuration examples for both local development and production setups. - Enhanced the quick start guide to reflect the new installation and configuration process. - Updated the Chinese version of the documentation to ensure consistency with the English version.
1 parent 59511e4 commit a5fd2d8

5 files changed

Lines changed: 337 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 79 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,86 @@ WaveForge MCP task management system is now largely complete! Core project manag
3838

3939
## 🚀 Getting Started
4040

41-
For detailed instructions on installation, configuration, and usage, please see the [**Usage Guide (`USAGE.md`)**](./USAGE.md).
41+
WaveForge is now published to npm! The easiest way to get started is using `npx`.
42+
43+
### MCP Client Configuration
44+
45+
Configure your MCP client (like Cursor or Kiro) to use WaveForge:
46+
47+
**JSON format (`.cursor/mcp.json`):**
48+
```json
49+
{
50+
"mcpServers": {
51+
"waveforge": {
52+
"type": "stdio",
53+
"command": "npx",
54+
"args": ["-y", "waveforge@latest"],
55+
"env": {
56+
"WF_LOG_LEVEL": "SILENT",
57+
"WF_DEBUG": "false",
58+
"npm_config_loglevel": "silent",
59+
"npm_config_yes": "true"
60+
}
61+
}
62+
}
63+
}
64+
```
65+
66+
**TOML format (`.codex/config.toml`):**
67+
```toml
68+
[mcp_servers.waveforge]
69+
command = "npx"
70+
args = ["-y", "waveforge@latest"]
71+
env = { "WF_LOG_LEVEL" = "SILENT", "WF_DEBUG" = "false", "npm_config_loglevel" = "silent", "npm_config_yes" = "true" }
72+
```
4273

43-
**Quick Start**: Want to jump right in? Check out the [**Quick Start Guide (`docs/quick-start.md`)**](./docs/quick-start.md) for a complete workflow example.
74+
### Local Development
75+
76+
If you want to contribute to WaveForge or run a local version:
77+
78+
1. **Clone the repository**:
79+
```bash
80+
git clone https://github.com/DeadWaveWave/waveforge.git
81+
cd waveforge
82+
```
83+
84+
2. **Install dependencies**:
85+
```bash
86+
pnpm install
87+
```
88+
89+
3. **Run in development mode**:
90+
```bash
91+
pnpm dev
92+
```
93+
94+
4. **Configure your MCP client to use the local build**:
95+
96+
**JSON format (`.cursor/mcp.json`):**
97+
```json
98+
{
99+
"mcpServers": {
100+
"waveforge": {
101+
"type": "stdio",
102+
"command": "node",
103+
"args": ["/path/to/your/waveforge/dist/esm/server.js"],
104+
"env": {
105+
"WF_LOG_LEVEL": "SILENT"
106+
}
107+
}
108+
}
109+
}
110+
```
111+
112+
**TOML format (`.codex/config.toml`):**
113+
```toml
114+
[mcp_servers.waveforge]
115+
command = "node"
116+
args = ["/path/to/your/waveforge/dist/esm/server.js"]
117+
env = { "WF_LOG_LEVEL" = "SILENT" }
118+
```
119+
120+
For more detailed instructions, see the [**Usage Guide (`USAGE.md`)**](./USAGE.md) and [**Quick Start Guide (`docs/quick-start.md`)**](./docs/quick-start.md).
44121
45122
If you encounter any issues, check the [**Troubleshooting Guide (`docs/troubleshooting.md`)**](./docs/troubleshooting.md) for known problems and solutions.
46123

‎README.zh-CN.md‎

Lines changed: 79 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,86 @@ WaveForge MCP 任务管理系统已基本完成！核心的项目管理和任务
3939

4040
## 🚀 快速上手
4141

42-
关于安装、配置和使用的详细说明，请参阅 [**使用指南 (`USAGE.md`)**](./USAGE.md)。
42+
WaveForge 已经发布到 npm！最简单的上手方式是使用 `npx`。
43+
44+
### MCP 客户端配置
45+
46+
配置你的 MCP 客户端（如 Cursor 或 Kiro）以使用 WaveForge：
47+
48+
**JSON 格式 (`.cursor/mcp.json`):**
49+
```json
50+
{
51+
"mcpServers": {
52+
"waveforge": {
53+
"type": "stdio",
54+
"command": "npx",
55+
"args": ["-y", "waveforge@latest"],
56+
"env": {
57+
"WF_LOG_LEVEL": "SILENT",
58+
"WF_DEBUG": "false",
59+
"npm_config_loglevel": "silent",
60+
"npm_config_yes": "true"
61+
}
62+
}
63+
}
64+
}
65+
```
66+
67+
**TOML 格式 (`.codex/config.toml`):**
68+
```toml
69+
[mcp_servers.waveforge]
70+
command = "npx"
71+
args = ["-y", "waveforge@latest"]
72+
env = { "WF_LOG_LEVEL" = "SILENT", "WF_DEBUG" = "false", "npm_config_loglevel" = "silent", "npm_config_yes" = "true" }
73+
```
4374

44-
**快速开始**：想要立即体验？查看 [**快速开始指南 (`docs/quick-start.zh-CN.md`)**](./docs/quick-start.zh-CN.md) 了解完整的工作流程示例。
75+
### 本地开发
76+
77+
如果你想为 WaveForge 贡献代码或运行本地版本：
78+
79+
1. **克隆仓库**：
80+
```bash
81+
git clone https://github.com/DeadWaveWave/waveforge.git
82+
cd waveforge
83+
```
84+
85+
2. **安装依赖**：
86+
```bash
87+
pnpm install
88+
```
89+
90+
3. **运行开发模式**：
91+
```bash
92+
pnpm dev
93+
```
94+
95+
4. **配置 MCP 客户端使用本地构建**：
96+
97+
**JSON 格式 (`.cursor/mcp.json`):**
98+
```json
99+
{
100+
"mcpServers": {
101+
"waveforge": {
102+
"type": "stdio",
103+
"command": "node",
104+
"args": ["/path/to/your/waveforge/dist/esm/server.js"],
105+
"env": {
106+
"WF_LOG_LEVEL": "SILENT"
107+
}
108+
}
109+
}
110+
}
111+
```
112+
113+
**TOML 格式 (`.codex/config.toml`):**
114+
```toml
115+
[mcp_servers.waveforge]
116+
command = "node"
117+
args = ["/path/to/your/waveforge/dist/esm/server.js"]
118+
env = { "WF_LOG_LEVEL" = "SILENT" }
119+
```
120+
121+
关于更详细的说明，请参阅 [**使用指南 (`USAGE.md`)**](./USAGE.md) 和 [**快速开始指南 (`docs/quick-start.zh-CN.md`)**](./docs/quick-start.zh-CN.md)。
45122
46123
如果遇到任何问题，请查看 [**故障排除指南 (`docs/troubleshooting.md`)**](./docs/troubleshooting.md) 获取已知问题的解决方案。
47124

‎USAGE.md‎

Lines changed: 104 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,45 +2,97 @@
22

33
This document provides detailed instructions for setting up, configuring, and using the WaveForge MCP server.
44

5-
## 🚀 Quick Start
5+
## 🚀 Installation & Setup
66

7-
### Environment Requirements
7+
WaveForge is available as an npm package. The recommended way to use it is with `npx`, which ensures you are always using the latest version without a global installation.
88

9-
- Node.js >= 18.0.0
10-
- pnpm (recommended) or npm
9+
### MCP Client Configuration
1110

12-
### Installation
11+
Add the following configuration to your MCP client (e.g., Cursor, Kiro):
1312

14-
```bash
15-
pnpm install
13+
**JSON format (`.cursor/mcp.json`):**
14+
```json
15+
{
16+
"mcpServers": {
17+
"waveforge": {
18+
"type": "stdio",
19+
"command": "npx",
20+
"args": ["-y", "waveforge@latest"],
21+
"env": {
22+
"WF_LOG_LEVEL": "SILENT",
23+
"WF_DEBUG": "false",
24+
"npm_config_loglevel": "silent",
25+
"npm_config_yes": "true"
26+
}
27+
}
28+
}
29+
}
1630
```
1731

18-
### Development Mode
19-
20-
```bash
21-
pnpm dev
32+
**TOML format (`.codex/config.toml`):**
33+
```toml
34+
[mcp_servers.waveforge]
35+
command = "npx"
36+
args = ["-y", "waveforge@latest"]
37+
env = { "WF_LOG_LEVEL" = "SILENT", "WF_DEBUG" = "false", "npm_config_loglevel" = "silent", "npm_config_yes" = "true" }
2238
```
2339

24-
### Build
40+
After adding the configuration, reload your MCP client.
41+
42+
### For Local Development
43+
44+
If you plan to contribute to WaveForge, you'll need to set up a local development environment.
45+
46+
#### Environment Requirements
47+
48+
- Node.js >= 18.0.0
49+
- pnpm (recommended) or npm
50+
51+
#### Setup
2552

2653
```bash
54+
# 1. Clone the repository
55+
git clone https://github.com/DeadWaveWave/waveforge.git
56+
cd waveforge
57+
58+
# 2. Install dependencies
59+
pnpm install
60+
61+
# 3. Build the project
2762
pnpm build
2863
```
2964

30-
### Testing
65+
#### Running Locally
66+
67+
You can run the server in development mode, which will watch for changes:
3168

3269
```bash
33-
pnpm test
70+
pnpm dev
3471
```
3572

36-
### Start Server
73+
To use your local build with an MCP client, update your configuration to point to the local server script:
3774

38-
```bash
39-
# Development mode
40-
pnpm dev
75+
**JSON format (`.cursor/mcp.json`):**
76+
```json
77+
{
78+
"mcpServers": {
79+
"waveforge": {
80+
"command": "node",
81+
"args": ["/path/to/your/waveforge/dist/esm/server.js"],
82+
"env": {
83+
"WF_LOG_LEVEL": "SILENT"
84+
}
85+
}
86+
}
87+
}
88+
```
4189

42-
# Production mode
43-
pnpm start
90+
**TOML format (`.codex/config.toml`):**
91+
```toml
92+
[mcp_servers.waveforge]
93+
command = "node"
94+
args = ["/path/to/your/waveforge/dist/esm/server.js"]
95+
env = { "WF_LOG_LEVEL" = "SILENT" }
4496
```
4597

4698
## 🔧 MCP Tools
@@ -709,11 +761,11 @@ The `project_info` tool provides comprehensive health monitoring for your projec
709761
710762
| Issue Type | Description | Auto-Fix | Manual Steps |
711763
| -------------------- | ----------------------------- | -------- | ----------------------------- |
712-
| `missing_directory` | Required directories missing | ✅ Yes | Re-run connect_project |
713-
| `corrupted_file` | JSON files damaged | ✅ Yes | Restore from backup if needed |
714-
| `permission_denied` | Insufficient file permissions | ❌ No | Fix directory permissions |
715-
| `template_missing` | Template files not found | ✅ Yes | Will copy from defaults |
716-
| `index_inconsistent` | Task index out of sync | ✅ Yes | Will rebuild automatically |
764+
| `missing_directory` | Required directories missing | ✅ Yes | Re-run connect_project |
765+
| `corrupted_file` | JSON files damaged | ✅ Yes | Restore from backup if needed |
766+
| `permission_denied` | Insufficient file permissions | ❌ No | Fix directory permissions |
767+
| `template_missing` | Template files not found | ✅ Yes | Will copy from defaults |
768+
| `index_inconsistent` | Task index out of sync | ✅ Yes | Will rebuild automatically |
717769
718770
#### Preventive Health Measures
719771
@@ -1008,6 +1060,7 @@ When possible, continue operation with reduced functionality:
10081060
10091061
Add the following to your MCP client configuration:
10101062
1063+
**JSON format (`.cursor/mcp.json`):**
10111064
```json
10121065
{
10131066
"mcpServers": {
@@ -1035,10 +1088,19 @@ Add the following to your MCP client configuration:
10351088
}
10361089
```
10371090
1091+
**TOML format (`.codex/config.toml`):**
1092+
```toml
1093+
[mcp_servers.waveforge]
1094+
command = "node"
1095+
args = ["path/to/waveforge/dist/esm/server.js"]
1096+
env = { "WF_LOG_LEVEL" = "SILENT", "WF_DEBUG" = "false" }
1097+
```
1098+
10381099
#### Security-Enhanced Configuration
10391100
10401101
For environments requiring higher security:
10411102
1103+
**JSON format (`.cursor/mcp.json`):**
10421104
```json
10431105
{
10441106
"mcpServers": {
@@ -1059,10 +1121,19 @@ For environments requiring higher security:
10591121
}
10601122
```
10611123
1124+
**TOML format (`.codex/config.toml`):**
1125+
```toml
1126+
[mcp_servers.waveforge]
1127+
command = "node"
1128+
args = ["path/to/waveforge/dist/esm/server.js"]
1129+
env = { "WF_LOG_LEVEL" = "SILENT", "WF_DEBUG" = "false", "WF_SECURITY_MODE" = "strict", "WF_ALLOWED_PATHS" = "/Users/username/Development,/Users/username/Projects" }
1130+
```
1131+
10621132
#### Development Configuration
10631133
10641134
For development and debugging:
10651135
1136+
**JSON format (`.cursor/mcp.json`):**
10661137
```json
10671138
{
10681139
"mcpServers": {
@@ -1082,6 +1153,14 @@ For development and debugging:
10821153
}
10831154
```
10841155
1156+
**TOML format (`.codex/config.toml`):**
1157+
```toml
1158+
[mcp_servers.waveforge]
1159+
command = "node"
1160+
args = ["path/to/waveforge/dist/esm/server.js"]
1161+
env = { "WF_LOG_LEVEL" = "DEBUG", "WF_DEBUG" = "true", "WF_AUDIT_LOG" = "true" }
1162+
```
1163+
10851164
#### Configuration Options Explained
10861165
10871166
**Environment Variables:**

0 commit comments

Comments
 (0)