Skip to content

Commit c1268e6

Browse files
ysyneuclaude
ysyneu
and
claude
committed
docs: add MCP Server and Terraform Provider documentation
Add a new Developer tab with complete documentation for both the Flashduty MCP Server (16 tools across 6 toolsets) and Terraform Provider (12 resources, 13 data sources). Includes overview, quick start, and full reference pages in both Chinese and English. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent ca92f0d commit c1268e6

17 files changed

Lines changed: 5822 additions & 0 deletions

‎docs.json‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -432,6 +432,38 @@
432432
]
433433
}
434434
]
435+
},
436+
{
437+
"tab": "开发者",
438+
"icon": "code",
439+
"groups": [
440+
{
441+
"group": "Open API",
442+
"pages": [
443+
"zh/openapi/introduction",
444+
"zh/openapi/pagination",
445+
"zh/openapi/rate-limits"
446+
]
447+
},
448+
{
449+
"group": "MCP Server",
450+
"pages": [
451+
"zh/developer/mcp-server/overview",
452+
"zh/developer/mcp-server/quick-start",
453+
"zh/developer/mcp-server/tools-reference",
454+
"zh/developer/mcp-server/configuration"
455+
]
456+
},
457+
{
458+
"group": "Terraform Provider",
459+
"pages": [
460+
"zh/developer/terraform/overview",
461+
"zh/developer/terraform/quick-start",
462+
"zh/developer/terraform/resource-reference",
463+
"zh/developer/terraform/data-source-reference"
464+
]
465+
}
466+
]
435467
}
436468
]
437469
},
@@ -848,6 +880,38 @@
848880
]
849881
}
850882
]
883+
},
884+
{
885+
"tab": "Developer",
886+
"icon": "code",
887+
"groups": [
888+
{
889+
"group": "Open API",
890+
"pages": [
891+
"en/openapi/introduction",
892+
"en/openapi/pagination",
893+
"en/openapi/rate-limits"
894+
]
895+
},
896+
{
897+
"group": "MCP Server",
898+
"pages": [
899+
"en/developer/mcp-server/overview",
900+
"en/developer/mcp-server/quick-start",
901+
"en/developer/mcp-server/tools-reference",
902+
"en/developer/mcp-server/configuration"
903+
]
904+
},
905+
{
906+
"group": "Terraform Provider",
907+
"pages": [
908+
"en/developer/terraform/overview",
909+
"en/developer/terraform/quick-start",
910+
"en/developer/terraform/resource-reference",
911+
"en/developer/terraform/data-source-reference"
912+
]
913+
}
914+
]
851915
}
852916
]
853917
}

‎en/developer/mcp-server/configuration.mdx‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
---
2+
title: "Configuration"
3+
description: "Flashduty MCP Server configuration reference, including toolset filtering, read-only mode, output format, environment variables, command-line arguments, and logging configuration."
4+
---
5+
6+
Flashduty MCP Server supports flexible configuration options. You can choose remote or local configuration approaches based on your deployment scenario.
7+
8+
## Configuration priority
9+
10+
When multiple configuration methods are used simultaneously, they take effect in the following priority order:
11+
12+
```
13+
Command-line arguments > Environment variables > Configuration file > Default values
14+
```
15+
16+
<Note>
17+
The remote service only supports configuration through URL parameters. Configuration files and command-line arguments are not supported.
18+
</Note>
19+
20+
## Remote service configuration
21+
22+
When using the remote service (`https://mcp.flashcat.cloud/mcp`), configure through URL query parameters:
23+
24+
```json
25+
{
26+
"mcpServers": {
27+
"flashduty": {
28+
"url": "https://mcp.flashcat.cloud/mcp?toolsets=incidents,users&read_only=true",
29+
"headers": {
30+
"Authorization": "Bearer <your_flashduty_app_key>"
31+
}
32+
}
33+
}
34+
}
35+
```
36+
37+
**Supported URL parameters**
38+
39+
| Parameter | Description | Example |
40+
| --- | --- | --- |
41+
| `toolsets` | Enabled toolsets, comma-separated | `toolsets=incidents,users,channels` |
42+
| `read_only` | Enable read-only mode | `read_only=true` |
43+
| `base_url` | Custom API address | `base_url=https://custom-api.example.com` |
44+
45+
**Authentication**
46+
47+
Pass the APP Key through the HTTP header `Authorization` in the format `Bearer <your_app_key>`.
48+
49+
## Local service configuration
50+
51+
### Environment variables
52+
53+
| Variable | Description | Required | Default |
54+
| --- | --- | --- | --- |
55+
| `FLASHDUTY_APP_KEY` | Flashduty APP Key | Yes | - |
56+
| `FLASHDUTY_TOOLSETS` | Enabled toolsets, comma-separated | No | All toolsets |
57+
| `FLASHDUTY_READ_ONLY` | Read-only mode (`1` or `true`) | No | `false` |
58+
| `FLASHDUTY_OUTPUT_FORMAT` | Output format (`json` or `toon`) | No | `json` |
59+
| `FLASHDUTY_BASE_URL` | Flashduty API address | No | `https://api.flashcat.cloud` |
60+
| `FLASHDUTY_LOG_FILE` | Log file path | No | stderr |
61+
| `FLASHDUTY_ENABLE_COMMAND_LOGGING` | Log requests/responses | No | `false` |
62+
| `TZ` | Log timestamp timezone | No | System default (falls back to `Asia/Shanghai` in containers) |
63+
64+
### Command-line arguments
65+
66+
```bash
67+
./flashduty-mcp-server stdio \
68+
--app-key your_app_key_here \
69+
--toolsets incidents,users,channels \
70+
--read-only \
71+
--output-format toon \
72+
--log-file /var/log/flashduty-mcp.log \
73+
--enable-command-logging
74+
```
75+
76+
| Argument | Description | Corresponding environment variable |
77+
| --- | --- | --- |
78+
| `--app-key` | Flashduty APP Key | `FLASHDUTY_APP_KEY` |
79+
| `--toolsets` | Enabled toolsets, comma-separated | `FLASHDUTY_TOOLSETS` |
80+
| `--read-only` | Enable read-only mode | `FLASHDUTY_READ_ONLY` |
81+
| `--output-format` | Output format (`json` or `toon`) | `FLASHDUTY_OUTPUT_FORMAT` |
82+
| `--base-url` | Flashduty API address | `FLASHDUTY_BASE_URL` |
83+
| `--log-file` | Log file path | `FLASHDUTY_LOG_FILE` |
84+
| `--enable-command-logging` | Log requests/responses | `FLASHDUTY_ENABLE_COMMAND_LOGGING` |
85+
| `--export-translations` | Export translation config to JSON file | - |
86+
87+
## Toolset filtering
88+
89+
All toolsets are enabled by default. You can use the `toolsets` parameter to enable only the toolsets you need, reducing context size and helping the LLM select tools more accurately.
90+
91+
**Available toolsets**
92+
93+
| Toolset | Description | Tool count | Contains write tools |
94+
| --- | --- | --- | --- |
95+
| `incidents` | Incident lifecycle management | 8 | Yes |
96+
| `changes` | Change record queries | 1 | No |
97+
| `status_page` | Status page management | 4 | Yes |
98+
| `users` | Member and team queries | 2 | No |
99+
| `channels` | Channels and escalation rules | 2 | No |
100+
| `fields` | Custom field definitions | 1 | No |
101+
102+
Use `all` to enable all toolsets.
103+
104+
<Tip>
105+
If you only need query functionality, it is recommended to enable both toolset filtering and read-only mode. This minimizes the tool list and improves the AI assistant's response accuracy.
106+
</Tip>
107+
108+
**Configuration examples**
109+
110+
<CodeGroup>
111+
```bash Environment variable
112+
export FLASHDUTY_TOOLSETS="incidents,users,channels"
113+
```
114+
115+
```bash Command-line argument
116+
./flashduty-mcp-server stdio --toolsets incidents,users,channels
117+
```
118+
119+
```json Remote service URL parameter
120+
{
121+
"url": "https://mcp.flashcat.cloud/mcp?toolsets=incidents,users,channels"
122+
}
123+
```
124+
</CodeGroup>
125+
126+
## Read-only mode
127+
128+
When read-only mode is enabled, all write tools are disabled and only query tools are retained. This is suitable for scenarios with higher security requirements.
129+
130+
Disabled write tools:
131+
- `create_incident` - Create an incident
132+
- `update_incident` - Update an incident
133+
- `ack_incident` - Acknowledge an incident
134+
- `close_incident` - Close an incident
135+
- `create_status_incident` - Create a status page incident
136+
- `create_change_timeline` - Add a change timeline entry
137+
138+
<CodeGroup>
139+
```bash Environment variable
140+
export FLASHDUTY_READ_ONLY=true
141+
```
142+
143+
```bash Command-line argument
144+
./flashduty-mcp-server stdio --read-only
145+
```
146+
147+
```json Remote service URL parameter
148+
{
149+
"url": "https://mcp.flashcat.cloud/mcp?read_only=true"
150+
}
151+
```
152+
</CodeGroup>
153+
154+
## Output format
155+
156+
MCP Server supports two output formats:
157+
158+
### JSON (default)
159+
160+
Standard JSON format with the best compatibility:
161+
162+
```json
163+
{"members":[{"person_id":1,"person_name":"Alice"},{"person_id":2,"person_name":"Bob"}],"total":2}
164+
```
165+
166+
### TOON (token-optimized)
167+
168+
[TOON (Token-Oriented Object Notation)](https://github.com/toon-format/toon) is a compact format that reduces token consumption by 30-50%, particularly suitable for LLM scenarios:
169+
170+
```
171+
members[2]{person_id,person_name}:
172+
1,Alice
173+
2,Bob
174+
total: 2
175+
```
176+
177+
<Tip>
178+
TOON format works best with uniformly structured object arrays (such as member lists, incident lists). Mainstream LLMs can correctly parse TOON format.
179+
</Tip>
180+
181+
<CodeGroup>
182+
```bash Environment variable
183+
export FLASHDUTY_OUTPUT_FORMAT=toon
184+
```
185+
186+
```bash Command-line argument
187+
./flashduty-mcp-server stdio --output-format toon
188+
```
189+
</CodeGroup>
190+
191+
## Custom tool descriptions (local only)
192+
193+
You can override tool default descriptions for internationalization or team customization purposes.
194+
195+
### Configuration file
196+
197+
Create `flashduty-mcp-server-config.json` in the same directory as the binary:
198+
199+
```json
200+
{
201+
"TOOL_CREATE_INCIDENT_DESCRIPTION": "Create a new incident ticket",
202+
"TOOL_LIST_TEAMS_DESCRIPTION": "List all teams in the account"
203+
}
204+
```
205+
206+
### Environment variables
207+
208+
Use the `FLASHDUTY_MCP_` prefix followed by the description key name:
209+
210+
```bash
211+
export FLASHDUTY_MCP_TOOL_CREATE_INCIDENT_DESCRIPTION="Create a new incident ticket"
212+
```
213+
214+
<Note>
215+
Custom tool descriptions are only available with local deployments. The remote service does not support this feature.
216+
</Note>
217+
218+
## Logging configuration
219+
220+
### Log file
221+
222+
Logs are output to stderr by default. You can specify a log file path using `--log-file` or `FLASHDUTY_LOG_FILE`:
223+
224+
```bash
225+
./flashduty-mcp-server stdio --log-file /var/log/flashduty-mcp.log
226+
```
227+
228+
### Request logging
229+
230+
When `--enable-command-logging` is enabled, the service logs detailed information about all MCP requests and responses, which is useful for debugging.
231+
232+
### Timezone configuration
233+
234+
Control the timezone of log timestamps using the `TZ` environment variable:
235+
236+
```bash
237+
# Docker example
238+
docker run -i --rm \
239+
-e FLASHDUTY_APP_KEY=<your-app-key> \
240+
-e TZ=Asia/Shanghai \
241+
registry.flashcat.cloud/public/flashduty-mcp-server
242+
```
243+
244+
Common timezone values: `Asia/Shanghai`, `America/New_York`, `Europe/London`, `UTC`.
245+
246+
<Tip>
247+
In container environments without timezone data (such as distroless images), if `TZ` is not set, the timezone automatically falls back to `Asia/Shanghai`.
248+
</Tip>
249+
250+
### Security features
251+
252+
MCP Server includes the following built-in logging security features:
253+
254+
- **Data masking**: Sensitive information such as `APP_KEY` and `Authorization` headers is automatically masked in logs
255+
- **Log truncation**: Oversized request/response bodies are automatically truncated (default 2KB) to prevent log bloat
256+
- **Trace correlation**: Supports the W3C Trace Context standard (`traceparent`), with logs automatically correlated by `trace_id` for cross-service tracing
257+
258+
## Complete Docker configuration example
259+
260+
```bash
261+
docker run -i --rm \
262+
-e FLASHDUTY_APP_KEY=<your-app-key> \
263+
-e FLASHDUTY_TOOLSETS="incidents,users,channels" \
264+
-e FLASHDUTY_READ_ONLY=1 \
265+
-e FLASHDUTY_OUTPUT_FORMAT=toon \
266+
-e TZ=Asia/Shanghai \
267+
registry.flashcat.cloud/public/flashduty-mcp-server
268+
```
269+
270+
Corresponding MCP client configuration:
271+
272+
```json
273+
{
274+
"mcpServers": {
275+
"flashduty": {
276+
"command": "docker",
277+
"args": [
278+
"run", "-i", "--rm",
279+
"-e", "FLASHDUTY_APP_KEY",
280+
"-e", "FLASHDUTY_TOOLSETS=incidents,users,channels",
281+
"-e", "FLASHDUTY_READ_ONLY=1",
282+
"-e", "FLASHDUTY_OUTPUT_FORMAT=toon",
283+
"-e", "TZ=Asia/Shanghai",
284+
"registry.flashcat.cloud/public/flashduty-mcp-server"
285+
],
286+
"env": {
287+
"FLASHDUTY_APP_KEY": "your_flashduty_app_key"
288+
}
289+
}
290+
}
291+
}
292+
```

0 commit comments

Comments
 (0)