@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 CHANGED
@@ -1,3 +1,207 @@
1
- # Temporary Holding Version
1
+ # 🎟️ TeamDynamix MCP Server (unofficial)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ![NPM Version](https://img.shields.io/npm/v/@voxslopuli/teamdynamix-mcp) [![CI](https://github.com/voxslopuli/teamdynamix-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/voxslopuli/teamdynamix-mcp/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/voxslopuli/teamdynamix-mcp/graph/badge.svg?token=kYslnQkMFy)](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