@voxslopuli/teamdynamix-mcp 0.0.0-stage → 0.4.0
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.
- package/README.md +206 -2
- package/index.d.ts +1 -0
- package/index.js +2083 -0
- package/index.js.map +1 -0
- package/package.json +45 -4
package/README.md
CHANGED
|
@@ -1,3 +1,207 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 🎟️ TeamDynamix MCP Server (unofficial)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
 [](https://github.com/voxslopuli/teamdynamix-mcp/actions/workflows/ci.yml) [](https://codecov.io/gh/voxslopuli/teamdynamix-mcp)
|
|
4
|
+
|
|
5
|
+
A TypeScript [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that exposes [TeamDynamix](https://www.teamdynamix.com/) ITSM capabilities as agent-callable tools. Designed for AI agents and MCP clients that need structured, safety-gated access to TeamDynamix operations.
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- **11 domain gateway tools** that route validated actions across discovery,
|
|
10
|
+
tickets, relationships, KB, assets, CMDB, people, services, projects,
|
|
11
|
+
time, and reference data
|
|
12
|
+
- **Safe by default**: write, delete, and admin tools disabled until
|
|
13
|
+
explicitly opted in; destructive operations require `confirm: true`
|
|
14
|
+
- **Two auth modes**: standard (username/password) and admin (BEID/WebServicesKey)
|
|
15
|
+
- **Covers 207 API endpoints** across all TeamDynamix domains, verified against the SDK route manifest
|
|
16
|
+
- **Rate-limit aware**: SDK built-in retry with exponential backoff on 429 and 5xx responses
|
|
17
|
+
- **Zod-validated inputs**: schema enforcement before any API call
|
|
18
|
+
- **Agent skill and prompt included**: ready-to-use skill definition for
|
|
19
|
+
GitHub Copilot and compatible agents
|
|
20
|
+
|
|
21
|
+
## MCP Registry
|
|
22
|
+
|
|
23
|
+
This server is published to the [MCP Registry](https://modelcontextprotocol.io/) as `io.github.voxslopuli/teamdynamix-mcp`.
|
|
24
|
+
|
|
25
|
+
- **Registry name**: `io.github.voxslopuli/teamdynamix-mcp`
|
|
26
|
+
- **Install via registry**: `mcp-install io.github.voxslopuli/teamdynamix-mcp` (when available)
|
|
27
|
+
- **Manual install**: Use npm package `@voxslopuli/teamdynamix-mcp` as shown below
|
|
28
|
+
|
|
29
|
+
## Quick start (developer setup)
|
|
30
|
+
|
|
31
|
+
This quick start is for contributors running the server from source in this
|
|
32
|
+
repository. If you are a regular MCP client user, skip to
|
|
33
|
+
[MCP client configuration](#mcp-client-configuration) and use the `npx`
|
|
34
|
+
command examples.
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
# 1. Clone the repository
|
|
38
|
+
git clone https://github.com/voxslopuli/teamdynamix-mcp.git
|
|
39
|
+
cd teamdynamix-mcp
|
|
40
|
+
|
|
41
|
+
# 2. Install dependencies
|
|
42
|
+
pnpm install
|
|
43
|
+
|
|
44
|
+
# 3. Configure environment
|
|
45
|
+
cp .env.example .env
|
|
46
|
+
# Edit .env with your TeamDynamix credentials and base URL
|
|
47
|
+
|
|
48
|
+
# 4. Start the development server
|
|
49
|
+
pnpm dev
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Minimum required environment variables
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
TEAMDYNAMIX_BASE_URL=https://your-tenant.teamdynamix.com/TDWebApi
|
|
56
|
+
TEAMDYNAMIX_AUTH_MODE=standard # or: admin
|
|
57
|
+
TEAMDYNAMIX_USERNAME=you@example.com # standard mode
|
|
58
|
+
TEAMDYNAMIX_PASSWORD=your-password # standard mode
|
|
59
|
+
|
|
60
|
+
# Optional: default application IDs (used when app_id is omitted in tool calls)
|
|
61
|
+
TEAMDYNAMIX_DEFAULT_TICKET_APP_ID=12345
|
|
62
|
+
TEAMDYNAMIX_DEFAULT_ASSET_APP_ID=23456
|
|
63
|
+
TEAMDYNAMIX_DEFAULT_KB_APP_ID=34567
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
For admin mode, use `TEAMDYNAMIX_BEID` and `TEAMDYNAMIX_WEB_SERVICES_KEY` instead.
|
|
67
|
+
|
|
68
|
+
## MCP client configuration
|
|
69
|
+
|
|
70
|
+
> **Security notice:** Values shown above are placeholders. **Never commit real credentials to source control.**
|
|
71
|
+
> Inject secrets at runtime via a `.env` file (excluded by `.gitignore`), CI/CD secrets, or a secret manager.
|
|
72
|
+
|
|
73
|
+
### VS Code (`.vscode/mcp.json`)
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"servers": {
|
|
78
|
+
"teamdynamix": {
|
|
79
|
+
"type": "stdio",
|
|
80
|
+
"command": "npx",
|
|
81
|
+
"args": ["-y", "@voxslopuli/teamdynamix-mcp"],
|
|
82
|
+
"env": {
|
|
83
|
+
"TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
|
|
84
|
+
"TEAMDYNAMIX_AUTH_MODE": "standard",
|
|
85
|
+
"TEAMDYNAMIX_USERNAME": "you@example.com",
|
|
86
|
+
"TEAMDYNAMIX_PASSWORD": "your-password"
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Claude Desktop (`claude_desktop_config.json`)
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"mcpServers": {
|
|
98
|
+
"teamdynamix": {
|
|
99
|
+
"command": "npx",
|
|
100
|
+
"args": ["-y", "@voxslopuli/teamdynamix-mcp"],
|
|
101
|
+
"env": {
|
|
102
|
+
"TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
|
|
103
|
+
"TEAMDYNAMIX_AUTH_MODE": "standard",
|
|
104
|
+
"TEAMDYNAMIX_USERNAME": "you@example.com",
|
|
105
|
+
"TEAMDYNAMIX_PASSWORD": "your-password"
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Production (built bundle)
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
pnpm build # outputs to dist/
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"command": "npx",
|
|
121
|
+
"args": ["-y", "@voxslopuli/teamdynamix-mcp"]
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Verify connectivity
|
|
126
|
+
|
|
127
|
+
After connecting your MCP client, call `teamdynamix_discovery` with:
|
|
128
|
+
|
|
129
|
+
- `action: "server_status"`
|
|
130
|
+
- `payload: {}`
|
|
131
|
+
- `response_format: "json"`
|
|
132
|
+
|
|
133
|
+
A successful response shows `status.configured: true`.
|
|
134
|
+
|
|
135
|
+
## Domain gateway tools
|
|
136
|
+
|
|
137
|
+
Each gateway tool accepts:
|
|
138
|
+
|
|
139
|
+
- `action`: domain-specific operation name
|
|
140
|
+
- `payload`: object for that action’s parameters
|
|
141
|
+
- `response_format`: `"markdown"` or `"json"`
|
|
142
|
+
|
|
143
|
+
| Domain | Gateway tool |
|
|
144
|
+
| -------------------- | ---------------------------------- |
|
|
145
|
+
| Discovery | `teamdynamix_discovery` |
|
|
146
|
+
| Tickets | `teamdynamix_tickets` |
|
|
147
|
+
| Ticket relationships | `teamdynamix_ticket_relationships` |
|
|
148
|
+
| Knowledge Base | `teamdynamix_knowledge_base` |
|
|
149
|
+
| Assets | `teamdynamix_assets` |
|
|
150
|
+
| CMDB | `teamdynamix_cmdb` |
|
|
151
|
+
| People | `teamdynamix_people` |
|
|
152
|
+
| Services | `teamdynamix_services` |
|
|
153
|
+
| Projects | `teamdynamix_projects` |
|
|
154
|
+
| Time | `teamdynamix_time` |
|
|
155
|
+
| Reference data | `teamdynamix_reference_data` |
|
|
156
|
+
|
|
157
|
+
† Requires `confirm: true` in addition to write tools being enabled.
|
|
158
|
+
|
|
159
|
+
All write/mutating actions require `TEAMDYNAMIX_ENABLE_WRITE_TOOLS=true`.
|
|
160
|
+
|
|
161
|
+
## Safety defaults
|
|
162
|
+
|
|
163
|
+
| Flag | Default | Effect when `true` |
|
|
164
|
+
| --------------------------------- | ------- | --------------------------------------------------------- |
|
|
165
|
+
| `TEAMDYNAMIX_ENABLE_WRITE_TOOLS` | `false` | Enables all create/update/comment/mutation tools |
|
|
166
|
+
| `TEAMDYNAMIX_ENABLE_DELETE_TOOLS` | `false` | Enables asset, CI, service, and service category deletion |
|
|
167
|
+
| `TEAMDYNAMIX_ENABLE_ADMIN_TOOLS` | `false` | Enables admin-scope operations |
|
|
168
|
+
|
|
169
|
+
Destructive operations additionally require `confirm: true` in the
|
|
170
|
+
tool call regardless of the flag state.
|
|
171
|
+
|
|
172
|
+
## Agent skill
|
|
173
|
+
|
|
174
|
+
This repository ships a GitHub Copilot-compatible skill definition:
|
|
175
|
+
|
|
176
|
+
- **Skill**: [`skills/teamdynamix/SKILL.md`](skills/teamdynamix/SKILL.md)
|
|
177
|
+
— ID-first workflow patterns, safety branching rules, runbooks,
|
|
178
|
+
gotchas, and tool catalog
|
|
179
|
+
- **Agent prompt**:
|
|
180
|
+
[`prompts/teamdynamix-agent.prompt.md`](prompts/teamdynamix-agent.prompt.md)
|
|
181
|
+
— system prompt for agent mode with TeamDynamix context
|
|
182
|
+
|
|
183
|
+
Install the skill via your Copilot skill configuration
|
|
184
|
+
(see `skills/teamdynamix/SKILL.md` for full details).
|
|
185
|
+
|
|
186
|
+
## Documentation
|
|
187
|
+
|
|
188
|
+
| Section | Purpose |
|
|
189
|
+
| ----------------------------------------------- | ------------------------------------------------------------ |
|
|
190
|
+
| [Tutorials](docs/tutorials/index.md) | Step-by-step setup and first workflows |
|
|
191
|
+
| [How-to guides](docs/how-to/index.md) | Task-oriented recipes for real operations |
|
|
192
|
+
| [Reference](docs/reference/index.md) | Exhaustive tool catalog, configuration, safety model, errors |
|
|
193
|
+
| [Explanation](docs/explanation/index.md) | Architecture, auth model, safety rationale, rate limiting |
|
|
194
|
+
| [Development](docs/development/architecture.md) | Architecture, contributing, testing |
|
|
195
|
+
|
|
196
|
+
## Development
|
|
197
|
+
|
|
198
|
+
```sh
|
|
199
|
+
pnpm typecheck # TypeScript strict checks
|
|
200
|
+
pnpm lint # oxlint
|
|
201
|
+
pnpm test # vitest (200+ tests, 90%+ coverage)
|
|
202
|
+
pnpm build # tsup → dist/
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## License
|
|
206
|
+
|
|
207
|
+
MIT © [The Self Agency LLC](https://self.agency)
|
package/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
#!/usr/bin/env node
|