mcp-creatio 0.4.0 → 0.5.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.
Files changed (215) hide show
  1. package/README.md +252 -212
  2. package/dist/cli.d.ts +5 -0
  3. package/dist/cli.d.ts.map +1 -1
  4. package/dist/cli.js +18 -11
  5. package/dist/cli.js.map +1 -1
  6. package/dist/creatio/auth/auth.d.ts +2 -0
  7. package/dist/creatio/auth/auth.d.ts.map +1 -1
  8. package/dist/creatio/auth/auth.js.map +1 -1
  9. package/dist/creatio/auth/providers/base-provider.d.ts +1 -0
  10. package/dist/creatio/auth/providers/base-provider.d.ts.map +1 -1
  11. package/dist/creatio/auth/providers/base-provider.js +3 -0
  12. package/dist/creatio/auth/providers/base-provider.js.map +1 -1
  13. package/dist/creatio/auth/providers/oauth2-code-provider.d.ts +3 -0
  14. package/dist/creatio/auth/providers/oauth2-code-provider.d.ts.map +1 -1
  15. package/dist/creatio/auth/providers/oauth2-code-provider.js +30 -24
  16. package/dist/creatio/auth/providers/oauth2-code-provider.js.map +1 -1
  17. package/dist/creatio/providers/configuration-provider.d.ts +3 -2
  18. package/dist/creatio/providers/configuration-provider.d.ts.map +1 -1
  19. package/dist/creatio/providers/crud-provider.d.ts +2 -0
  20. package/dist/creatio/providers/crud-provider.d.ts.map +1 -1
  21. package/dist/creatio/services/configuration-service-provider.d.ts.map +1 -1
  22. package/dist/creatio/services/configuration-service-provider.js +11 -3
  23. package/dist/creatio/services/configuration-service-provider.js.map +1 -1
  24. package/dist/creatio/services/http-client.d.ts.map +1 -1
  25. package/dist/creatio/services/http-client.js +0 -1
  26. package/dist/creatio/services/http-client.js.map +1 -1
  27. package/dist/creatio/services/metadata-store.d.ts +5 -0
  28. package/dist/creatio/services/metadata-store.d.ts.map +1 -1
  29. package/dist/creatio/services/metadata-store.js +18 -6
  30. package/dist/creatio/services/metadata-store.js.map +1 -1
  31. package/dist/creatio/services/odata-crud-provider.d.ts +3 -1
  32. package/dist/creatio/services/odata-crud-provider.d.ts.map +1 -1
  33. package/dist/creatio/services/odata-crud-provider.js +31 -8
  34. package/dist/creatio/services/odata-crud-provider.js.map +1 -1
  35. package/dist/server/http/creatio-oauth-handlers.d.ts +0 -1
  36. package/dist/server/http/creatio-oauth-handlers.d.ts.map +1 -1
  37. package/dist/server/http/creatio-oauth-handlers.js +30 -23
  38. package/dist/server/http/creatio-oauth-handlers.js.map +1 -1
  39. package/dist/server/http/httpServer.d.ts +9 -0
  40. package/dist/server/http/httpServer.d.ts.map +1 -1
  41. package/dist/server/http/httpServer.js +34 -11
  42. package/dist/server/http/httpServer.js.map +1 -1
  43. package/dist/server/http/mcp-handlers.d.ts.map +1 -1
  44. package/dist/server/http/mcp-handlers.js +4 -1
  45. package/dist/server/http/mcp-handlers.js.map +1 -1
  46. package/dist/server/http/mcp-oauth-handlers.d.ts.map +1 -1
  47. package/dist/server/http/mcp-oauth-handlers.js +18 -6
  48. package/dist/server/http/mcp-oauth-handlers.js.map +1 -1
  49. package/dist/server/http/middleware.d.ts +7 -0
  50. package/dist/server/http/middleware.d.ts.map +1 -1
  51. package/dist/server/http/middleware.js +23 -0
  52. package/dist/server/http/middleware.js.map +1 -1
  53. package/dist/server/http/rate-limiter.d.ts +24 -0
  54. package/dist/server/http/rate-limiter.d.ts.map +1 -0
  55. package/dist/server/http/rate-limiter.js +42 -0
  56. package/dist/server/http/rate-limiter.js.map +1 -0
  57. package/dist/server/mcp/creatio-rest.d.ts +44 -0
  58. package/dist/server/mcp/creatio-rest.d.ts.map +1 -0
  59. package/dist/server/mcp/creatio-rest.js +26 -0
  60. package/dist/server/mcp/creatio-rest.js.map +1 -0
  61. package/dist/server/mcp/crtmcp/crt-mcp-client.d.ts +55 -0
  62. package/dist/server/mcp/crtmcp/crt-mcp-client.d.ts.map +1 -0
  63. package/dist/server/mcp/crtmcp/crt-mcp-client.js +67 -0
  64. package/dist/server/mcp/crtmcp/crt-mcp-client.js.map +1 -0
  65. package/dist/server/mcp/crtmcp/crt-mcp-tool-preparer.d.ts +20 -0
  66. package/dist/server/mcp/crtmcp/crt-mcp-tool-preparer.d.ts.map +1 -0
  67. package/dist/server/mcp/crtmcp/crt-mcp-tool-preparer.js +74 -0
  68. package/dist/server/mcp/crtmcp/crt-mcp-tool-preparer.js.map +1 -0
  69. package/dist/server/mcp/dataforge/dataforge-client.d.ts +64 -0
  70. package/dist/server/mcp/dataforge/dataforge-client.d.ts.map +1 -0
  71. package/dist/server/mcp/dataforge/dataforge-client.js +130 -0
  72. package/dist/server/mcp/dataforge/dataforge-client.js.map +1 -0
  73. package/dist/server/mcp/dataforge/dataforge-tool-preparer.d.ts +17 -0
  74. package/dist/server/mcp/dataforge/dataforge-tool-preparer.d.ts.map +1 -0
  75. package/dist/server/mcp/dataforge/dataforge-tool-preparer.js +42 -0
  76. package/dist/server/mcp/dataforge/dataforge-tool-preparer.js.map +1 -0
  77. package/dist/server/mcp/filters.d.ts.map +1 -1
  78. package/dist/server/mcp/filters.js +20 -4
  79. package/dist/server/mcp/filters.js.map +1 -1
  80. package/dist/server/mcp/globalsearch/globalsearch-client.d.ts +50 -0
  81. package/dist/server/mcp/globalsearch/globalsearch-client.d.ts.map +1 -0
  82. package/dist/server/mcp/globalsearch/globalsearch-client.js +118 -0
  83. package/dist/server/mcp/globalsearch/globalsearch-client.js.map +1 -0
  84. package/dist/server/mcp/globalsearch/globalsearch-tool-preparer.d.ts +16 -0
  85. package/dist/server/mcp/globalsearch/globalsearch-tool-preparer.d.ts.map +1 -0
  86. package/dist/server/mcp/globalsearch/globalsearch-tool-preparer.js +34 -0
  87. package/dist/server/mcp/globalsearch/globalsearch-tool-preparer.js.map +1 -0
  88. package/dist/server/mcp/json-schema-to-zod.d.ts +3 -0
  89. package/dist/server/mcp/json-schema-to-zod.d.ts.map +1 -0
  90. package/dist/server/mcp/json-schema-to-zod.js +54 -0
  91. package/dist/server/mcp/json-schema-to-zod.js.map +1 -0
  92. package/dist/server/mcp/server.d.ts +18 -0
  93. package/dist/server/mcp/server.d.ts.map +1 -1
  94. package/dist/server/mcp/server.js +93 -25
  95. package/dist/server/mcp/server.js.map +1 -1
  96. package/dist/server/mcp/tool-preparer.d.ts +26 -0
  97. package/dist/server/mcp/tool-preparer.d.ts.map +1 -0
  98. package/dist/server/mcp/tool-preparer.js +11 -0
  99. package/dist/server/mcp/tool-preparer.js.map +1 -0
  100. package/dist/server/mcp/tools-data.d.ts +69 -10
  101. package/dist/server/mcp/tools-data.d.ts.map +1 -1
  102. package/dist/server/mcp/tools-data.js +222 -32
  103. package/dist/server/mcp/tools-data.js.map +1 -1
  104. package/dist/server/oauth/oauth-server.d.ts +0 -1
  105. package/dist/server/oauth/oauth-server.d.ts.map +1 -1
  106. package/dist/server/oauth/oauth-server.js +11 -21
  107. package/dist/server/oauth/oauth-server.js.map +1 -1
  108. package/dist/server/oauth/storage.d.ts +0 -2
  109. package/dist/server/oauth/storage.d.ts.map +1 -1
  110. package/dist/server/oauth/storage.js +0 -6
  111. package/dist/server/oauth/storage.js.map +1 -1
  112. package/dist/server/oauth/validators.d.ts +6 -0
  113. package/dist/server/oauth/validators.d.ts.map +1 -1
  114. package/dist/server/oauth/validators.js +28 -0
  115. package/dist/server/oauth/validators.js.map +1 -1
  116. package/dist/services/session-context.d.ts +8 -7
  117. package/dist/services/session-context.d.ts.map +1 -1
  118. package/dist/services/session-context.js +7 -27
  119. package/dist/services/session-context.js.map +1 -1
  120. package/package.json +18 -9
  121. package/.dockerignore +0 -12
  122. package/.editorconfig +0 -14
  123. package/.eslintrc.cjs +0 -18
  124. package/.gitattributes +0 -8
  125. package/.github/workflows/docker-publish.yml +0 -50
  126. package/.prettierignore +0 -3
  127. package/.prettierrc +0 -9
  128. package/.vscode/launch.json +0 -23
  129. package/.vscode/mcp.json +0 -13
  130. package/.vscode/settings.json +0 -16
  131. package/Agent.md +0 -190
  132. package/Debug.md +0 -32
  133. package/Dockerfile +0 -23
  134. package/docs/coding-style.md +0 -30
  135. package/eslint.config.cjs +0 -95
  136. package/src/cli.ts +0 -162
  137. package/src/config-builder.ts +0 -76
  138. package/src/consts.ts +0 -3
  139. package/src/creatio/auth/auth-manager.ts +0 -27
  140. package/src/creatio/auth/auth.ts +0 -31
  141. package/src/creatio/auth/index.ts +0 -3
  142. package/src/creatio/auth/providers/base-oauth2-provider.ts +0 -62
  143. package/src/creatio/auth/providers/base-provider.ts +0 -42
  144. package/src/creatio/auth/providers/index.ts +0 -4
  145. package/src/creatio/auth/providers/legacy-provider.ts +0 -70
  146. package/src/creatio/auth/providers/oauth2-code-provider.ts +0 -252
  147. package/src/creatio/auth/providers/oauth2-provider.ts +0 -91
  148. package/src/creatio/auth/providers/type.ts +0 -5
  149. package/src/creatio/client-config.ts +0 -34
  150. package/src/creatio/engines/admin-operation/admin-operation-engine.ts +0 -44
  151. package/src/creatio/engines/configuration/configuration-engine.ts +0 -26
  152. package/src/creatio/engines/crud/crud-engine.ts +0 -47
  153. package/src/creatio/engines/engine-manager.ts +0 -157
  154. package/src/creatio/engines/engine-registry.ts +0 -39
  155. package/src/creatio/engines/engine.ts +0 -3
  156. package/src/creatio/engines/feature/feature-engine.ts +0 -20
  157. package/src/creatio/engines/index.ts +0 -10
  158. package/src/creatio/engines/process/process-engine.ts +0 -20
  159. package/src/creatio/engines/sys-settings/sys-settings-engine.ts +0 -41
  160. package/src/creatio/engines/user/user-engine.ts +0 -20
  161. package/src/creatio/index.ts +0 -6
  162. package/src/creatio/provider-context.ts +0 -21
  163. package/src/creatio/providers/admin-operation-provider.ts +0 -34
  164. package/src/creatio/providers/configuration-provider.ts +0 -22
  165. package/src/creatio/providers/crud-provider.ts +0 -45
  166. package/src/creatio/providers/feature-provider.ts +0 -10
  167. package/src/creatio/providers/index.ts +0 -7
  168. package/src/creatio/providers/process-provider.ts +0 -15
  169. package/src/creatio/providers/sys-settings-provider.ts +0 -63
  170. package/src/creatio/providers/user-provider.ts +0 -12
  171. package/src/creatio/services/admin-operation-service-provider.ts +0 -115
  172. package/src/creatio/services/configuration-service-provider.ts +0 -127
  173. package/src/creatio/services/creatio-service-context.ts +0 -55
  174. package/src/creatio/services/feature-service-provider.ts +0 -60
  175. package/src/creatio/services/http-client.ts +0 -174
  176. package/src/creatio/services/index.ts +0 -10
  177. package/src/creatio/services/metadata-store.ts +0 -181
  178. package/src/creatio/services/odata-crud-provider.ts +0 -210
  179. package/src/creatio/services/process-service-provider.ts +0 -76
  180. package/src/creatio/services/sys-settings-service-provider.ts +0 -192
  181. package/src/creatio/services/user-info-provider.ts +0 -41
  182. package/src/index.ts +0 -44
  183. package/src/log.ts +0 -183
  184. package/src/server/http/creatio-oauth-handlers.ts +0 -146
  185. package/src/server/http/httpServer.ts +0 -150
  186. package/src/server/http/index.ts +0 -5
  187. package/src/server/http/mcp-handlers.ts +0 -92
  188. package/src/server/http/mcp-oauth-handlers.ts +0 -108
  189. package/src/server/http/middleware.ts +0 -91
  190. package/src/server/index.ts +0 -2
  191. package/src/server/mcp/filters.ts +0 -97
  192. package/src/server/mcp/index.ts +0 -1
  193. package/src/server/mcp/prompts-data.ts +0 -1292
  194. package/src/server/mcp/server.ts +0 -442
  195. package/src/server/mcp/tools-data.ts +0 -748
  196. package/src/server/oauth/client-manager.ts +0 -47
  197. package/src/server/oauth/index.ts +0 -6
  198. package/src/server/oauth/oauth-server.ts +0 -185
  199. package/src/server/oauth/storage.ts +0 -106
  200. package/src/server/oauth/token-manager.ts +0 -80
  201. package/src/server/oauth/types.ts +0 -55
  202. package/src/server/oauth/validators.ts +0 -56
  203. package/src/services/index.ts +0 -2
  204. package/src/services/session-context.ts +0 -232
  205. package/src/services/token-refresh-scheduler.ts +0 -68
  206. package/src/types/index.ts +0 -1
  207. package/src/types/network.ts +0 -7
  208. package/src/utils/context.ts +0 -49
  209. package/src/utils/env.ts +0 -12
  210. package/src/utils/index.ts +0 -5
  211. package/src/utils/mcp.ts +0 -8
  212. package/src/utils/network.ts +0 -65
  213. package/src/utils/pkce.ts +0 -39
  214. package/src/version.ts +0 -15
  215. package/tsconfig.json +0 -28
package/Agent.md DELETED
@@ -1,190 +0,0 @@
1
- # Agent Guide: MCP Creatio Server
2
-
3
- This document is for AI coding agents contributing to this repository. It explains project purpose, architecture, invariants, and safe extension patterns.
4
-
5
- ## 1. Purpose
6
-
7
- An implementation of a Model Context Protocol (MCP) server that exposes Creatio CRM to MCP-compatible AI clients (Claude Desktop, ChatGPT Connectors, GitHub Copilot, etc.).
8
-
9
- Primary goals:
10
-
11
- - Provide stable tool surface for CRUD, schema discovery, business process execution.
12
- - Enforce safe data operations (especially Activities ownership rules, date/time UTC handling).
13
- - Offer prompts that guide LLMs to use Creatio correctly.
14
-
15
- ## 2. High-Level Architecture
16
-
17
- ```
18
- src/
19
- creatio/ ← Low-level Creatio API client & auth providers
20
- server/ ← MCP server + HTTP layer (OAuth server, handlers)
21
- mcp/ ← MCP tool descriptors, prompts, filters builder
22
- oauth/ ← Local OAuth 2.1 authorization server for clients
23
- services/ ← Session/token refresh orchestration
24
- utils/ ← Reusable helpers (env, network, pkce, context)
25
- types/ ← Shared TypeScript interfaces & DTO shapes
26
- ```
27
-
28
- Key flows:
29
-
30
- 1. Client authenticates (legacy credentials OR OAuth2 variants).
31
- 2. MCP server registers tools using descriptors from `server/mcp/tools-data.ts`.
32
- 3. Tool handlers call into `CreatioEngineManager`, which resolves a `CreatioServiceContext` (built from `src/creatio/services/*`) and delegates work to the appropriate provider (CRUD, process, sys-settings, user).
33
- 4. Responses are normalized into MCP content blocks.
34
-
35
- ### Creatio Service Stack (LLM Cheat Sheet)
36
-
37
- ```
38
- CreatioServiceContext
39
- ├─ CreatioAuthManager → selects concrete auth provider (legacy / OAuth2 / OAuth2 code)
40
- ├─ CreatioHttpClient → transport + logging + retry + header helpers
41
- ├─ ODataMetadataStore → caches entity schemas per environment
42
- ├─ ODataCrudProvider → implements CrudProvider using http + metadata
43
- ├─ ProcessServiceProvider → POSTs to ProcessEngineService
44
- ├─ SysSettingsServiceProvider → DataService JSON endpoint
45
- ├─ FeatureServiceProvider → /rest/FeatureService/ClearFeaturesCacheForAllUsers
46
- ├─ AdminOperationServiceProvider → /rest/RightsService/{Upsert,Delete}AdminOperation[,Grantee]
47
- ├─ ConfigurationServiceProvider → generic /rest/<service>/<method> caller
48
- └─ UserInfoProvider → UserInfoService for current user data
49
- ```
50
-
51
- Usage pattern:
52
-
53
- - Handlers never craft raw fetch calls. They work through provider interfaces exposed by the context (`provider.crud`, `provider.process`, etc.).
54
- - If you need a new Creatio capability, add a dedicated provider (or extend an existing one) and wire it up inside `CreatioServiceContext`.
55
- - `CreatioHttpClient` should stay transport-focused (auth headers, retries, timing). Keep endpoint-specific logic inside providers or a dedicated endpoint helper.
56
-
57
- ## 3. Core Modules You Will Touch
58
-
59
- | Area | File(s) | Notes |
60
- | ---------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
61
- | Tool registration | `src/server/mcp/server.ts` | Add/remove tool handlers; keep descriptors in separate file. |
62
- | Tool schemas & text guidance | `src/server/mcp/tools-data.ts` | Use `zod` schemas; detailed descriptions help AI reasoning. |
63
- | Filters logic | `src/server/mcp/filters.ts` | Converts structured JSON filters into OData `$filter` strings. |
64
- | Prompts | `src/server/mcp/prompts-data.ts` | Pre-baked instructional prompts consumed by clients. |
65
- | Creatio API | `src/creatio/services/*` | `CreatioServiceContext` composes auth + http client + providers; extend providers instead of bypassing them. |
66
- | OAuth for clients | `src/server/oauth/*` | Maintains tokens for MCP clients; ephemeral memory by default. |
67
-
68
- ## 4. Invariants & Rules (Do NOT Break)
69
-
70
- 1. All date/time fields passed to Creatio MUST be UTC ISO8601 with `Z` suffix.
71
- 2. Activity creation: Always set `OwnerId` and `AuthorId` to current user's ContactId obtained via `get-current-user-info` unless user explicitly specifies another owner.
72
- 3. Avoid adding blocking network calls in tool descriptors—descriptors must be static; logic belongs in handlers.
73
- 4. Never silently swallow errors coming from Creatio—log via `log.error` then rethrow.
74
- 5. Keep tool names stable: lowercase kebab-case (e.g. `execute-process`).
75
- 6. Keep authentication precedence: Authorization Code > Client Credentials > Legacy.
76
- 7. Do not leak secrets or access tokens in tool responses.
77
- 8. `READONLY_MODE=true` must guarantee no mutation tools (`create`, `update`, `delete`, `execute-process`, `set-sys-settings-value`, `create-sys-setting`, `update-sys-setting-definition`, `refresh-feature-cache`, `upsert-admin-operation`, `delete-admin-operation`, `set-admin-operation-grantee`, `delete-admin-operation-grantee`, `call-configuration-service`) are registered.
78
-
79
- ## 5. Adding a New Tool (Checklist)
80
-
81
- 1. Define input shape in `tools-data.ts` using `zod`.
82
- 2. Provide rich description (include examples, edge cases, warnings).
83
- 3. Export descriptor & input schema.
84
- 4. Register in `server.ts` via `_registerHandlerWithDescriptor` (respect readonly mode if mutating).
85
- 5. Implement the handler by calling the appropriate provider on the `CreatioServiceContext` (via `CreatioEngineManager`); if functionality is missing, extend or add a provider under `src/creatio/services` rather than issuing raw fetch calls.
86
- 6. Ensure responses are formatted as `{ content: [{ type: 'text', text: JSON.stringify(result) }] }` when not already MCP native.
87
- 7. Add edge-case validation (empty arrays, invalid GUID, missing required filter fields).
88
- 8. Update documentation (README if public feature; otherwise just Agent.md).
89
-
90
- ## 6. Error Handling Pattern
91
-
92
- - Use `try/catch` in handlers ONLY if you need to wrap/transform the error.
93
- - Log with contextual tag: `log.error('mcp.tool.handler', err)`.
94
- - Throw the original error afterward (MCP layer will relay).
95
- - For validation failures rely on `withValidation(...)` wrapper.
96
-
97
- ## 7. Logging Guidelines
98
-
99
- - Use `log.info('mcp.tool.register', { tool })` when registering tools.
100
- - Use `log.warn` for non-fatal recoverable issues (e.g., partial data fetch).
101
- - Use `log.error` strictly for failures that abort the operation.
102
-
103
- ## 8. Performance Considerations
104
-
105
- - Prefer `select` + `expand` to limit payload size; educate users via descriptor text.
106
- - Batch calls carefully—avoid sequential redundant reads if data already provided.
107
- - Avoid adding expensive synchronous CPU logic inside handlers.
108
-
109
- ## 9. Security & Safety
110
-
111
- - Never echo passwords or client secrets back to clients.
112
- - Strip or mask token-like values if accidentally included in objects.
113
- - Validate GUID format (8-4-4-4-12 hex) when exposing user input into queries.
114
-
115
- ## 10. Testing (Minimal Approach)
116
-
117
- Currently no formal test suite. For quick validation:
118
-
119
- - Start server locally (`npm start`) and manually invoke tools from an MCP client.
120
- - Consider adding lightweight Jest tests for filter builder and client methods (future enhancement).
121
-
122
- ## 11. Versioning & Release
123
-
124
- - Increment `package.json` version; code reads dynamically via `src/version.ts`.
125
- - Use semantic prefixes in commits: `feat:`, `fix:`, `docs:`, `chore:`.
126
- - Tag releases: `git tag vX.Y.Z && git push --tags` (manual unless automated later).
127
-
128
- ## 12. Common Edge Cases
129
-
130
- | Case | Mitigation |
131
- | ----------------------------------------- | -------------------------------------------------------------- |
132
- | Empty `select` array supplied | Preprocess to `undefined` (already handled) |
133
- | Mixed raw `filter` + structured `filters` | Combine with `and` parenthesized in handler |
134
- | Invalid GUID quoting | Provide guidance text + possible pre-validation before sending |
135
- | Large result sets | Encourage `top` param (<200 recommended) |
136
- | Readonly mode attempt to mutate | Ensure mutation tools not registered |
137
-
138
- ## 13. Extending Authentication
139
-
140
- If adding new auth provider:
141
-
142
- 1. Create provider under `src/creatio/auth/providers/` implementing shared interface.
143
- 2. Add selection logic in `auth-manager.ts` maintaining precedence ordering.
144
- 3. Document environment variables clearly in README + Agent.md.
145
-
146
- ## 14. Prompts Extension
147
-
148
- - Add new prompt object in `prompts-data.ts` (`name`, `title`, `description`, `argsSchema`, `callback`).
149
- - Keep names unique and descriptive.
150
- - Avoid external network calls inside prompt callbacks.
151
-
152
- ## 15. Code Style
153
-
154
- Baseline rules live in `docs/coding-style.md`. Highlights:
155
-
156
- - Keep TypeScript strict (avoid `any`, prefer explicit interfaces).
157
- - Follow the class-member ordering guide (readonly fields → fields → getters → setters → constructor → methods, each ordered `private → protected → public`).
158
- - Prefix private fields/methods with `_`.
159
- - Use existing utility wrappers (e.g., `withValidation`).
160
- - Keep functions small; single responsibility.
161
- - Reuse logging tags already established.
162
-
163
- ## 16. What NOT To Do
164
-
165
- - Do not reintroduce removed tools (`search`, `fetch`) unless strong justification & design review.
166
- - Do not bypass `CreatioServiceContext`/providers with raw fetch calls scattered in handlers.
167
- - Do not embed long multi-megabyte payloads in commit history (limit sample data).
168
-
169
- ## 17. Quick Start for Agent Changes
170
-
171
- 1. Make code edits.
172
- 2. Run `npm run build` to ensure TypeScript passes.
173
- 3. Optionally lint: `npm run lint`.
174
- 4. Commit using conventional message.
175
- 5. Push; consider tag if version bump.
176
-
177
- ## 18. Future Enhancements (Suggestions)
178
-
179
- - Add Jest test suite for filter builder + auth flows.
180
- - Implement persistent token storage (e.g., file/Redis) for OAuth tokens.
181
- - Add rate limiting to prevent excessive query load.
182
- - Provide structured error codes instead of raw messages.
183
-
184
- ## 19. Contact Points
185
-
186
- If you need business logic clarification, check existing descriptor guidance first. Many patterns (date handling, ownership) are documented inline in `tools-data.ts`.
187
-
188
- ---
189
-
190
- **Summary:** Focus on safe MCP tool extension around Creatio CRM. Preserve invariants, keep descriptors rich, centralize API interactions, and avoid leaking credentials.
package/Debug.md DELETED
@@ -1,32 +0,0 @@
1
- # Debug Guide
2
-
3
- ## PowerShell ISE Quick Start
4
-
5
- 1. Open **Windows PowerShell ISE (x64)** with the working directory set to the project root.
6
- 2. Copy the snippet below into a new script tab (for example, save it as `debug-creatio.ps1`).
7
- 3. Update the placeholder values to match your Creatio instance.
8
- 4. Press `F5` (or click **Run Script**) to launch the server with the desired environment.
9
-
10
- ```powershell
11
- # debug-creatio.ps1
12
- # Sets temporary environment variables for the current ISE session
13
- # and starts the MCP Creatio server in development mode.
14
-
15
- $env:CREATIO_BASE_URL = "https://your-creatio.com"
16
- $env:CREATIO_LOGIN = "your_login"
17
- $env:CREATIO_PASSWORD = "your_password"
18
-
19
- # Optional: adjust logging verbosity or other flags here
20
- # $env:LOG_LEVEL = "debug"
21
-
22
- # Start the server with the configured environment
23
- npm start
24
- ```
25
-
26
- ### Notes
27
-
28
- - Environment variables assigned with `$env:` live only for the current ISE session; close the session to clear them.
29
- - If you prefer reusable configuration, convert the snippet into a standalone `.ps1` file and commit the real credentials to a secure secrets manager instead of the repository.
30
- - When debugging authentication, consider leveraging the existing logging utilities in `src/log.ts` to inspect token exchange flows.
31
- - For deeper tracing (e.g., OAuth callback handling), set breakpoints in `src/server/http/creatio-oauth-handlers.ts` and `src/server/mcp/server.ts` before running the script.
32
- - The `Debug MCP Creatio` configuration in `.vscode/launch.json` mirrors these environment variables; adjust the placeholder values there to attach VS Code's debugger directly to `npm start`.
package/Dockerfile DELETED
@@ -1,23 +0,0 @@
1
- # Minimal Dockerfile for MCP Creatio Server
2
- # Builds and runs with ts-node (no separate build step)
3
-
4
- FROM node:20-alpine AS base
5
-
6
- # App directory
7
- WORKDIR /app
8
-
9
- # Install production and dev deps (ts-node, types)
10
- COPY package.json package-lock.json* ./
11
- RUN npm ci || npm install
12
-
13
- # Copy source
14
- COPY . .
15
-
16
- # Environment (override at runtime)
17
- ENV PORT=3000
18
-
19
- # Expose MCP HTTP port
20
- EXPOSE 3000
21
-
22
- # Start the server (ts-node)
23
- CMD ["npm", "run", "start"]
@@ -1,30 +0,0 @@
1
- # Coding Style Guide
2
-
3
- This guide defines the class/member layout used across the project so every contributor (human or LLM) can keep the codebase consistent and easy to read.
4
-
5
- ## Class Member Ordering
6
-
7
- Group class members in the following order. Within each group sort by access level: `private` → `protected` → `public`.
8
-
9
- 1. **Fields (readonly)** – immutable state declared with `readonly`.
10
- 2. **Fields** – mutable fields.
11
- 3. **Properties (getters only)**.
12
- 4. **Properties with setters** – getter/setter pairs.
13
- 5. **Constructors**.
14
- 6. **Methods** – regular functions (again `private`, `protected`, `public`).
15
-
16
- Additional rules:
17
-
18
- - Prefix all private fields and methods with `_` (e.g., `_cache`, `_buildRequest`).
19
- - Prefer `protected` for members intended for subclasses, otherwise keep them `private` or `public`.
20
- - Avoid interleaving unrelated helper functions; keep the order strict even when a method depends on another declared later.
21
- - Use whitespace between groups to keep sections visually distinct.
22
-
23
- ## Clean Code Expectations
24
-
25
- - Keep methods small and single-purpose. Extract helpers rather than nesting complex logic.
26
- - Use descriptive names; avoid abbreviations unless they are domain-specific and already established.
27
- - Log through the shared `log` helper. Never swallow errors silently.
28
- - Adhere to existing TypeScript strictness (no implicit `any`).
29
-
30
- When updating or creating a class, run through this list to ensure the structure matches before submitting changes.
package/eslint.config.cjs DELETED
@@ -1,95 +0,0 @@
1
- module.exports = [
2
- {
3
- ignores: ['node_modules/**', 'dist/**', 'coverage/**'],
4
- },
5
- {
6
- files: ['**/*.{ts,tsx,js,jsx}'],
7
- languageOptions: {
8
- parser: require('@typescript-eslint/parser'),
9
- parserOptions: {
10
- project: ['./tsconfig.json'],
11
- tsconfigRootDir: __dirname,
12
- sourceType: 'module'
13
- }
14
- },
15
- plugins: {
16
- prettier: require('eslint-plugin-prettier'),
17
- '@typescript-eslint': require('@typescript-eslint/eslint-plugin'),
18
- import: require('eslint-plugin-import')
19
- },
20
- rules: {
21
- 'prettier/prettier': [
22
- 'error',
23
- {
24
- singleQuote: true,
25
- trailingComma: 'all',
26
- semi: true,
27
- printWidth: 100,
28
- useTabs: true,
29
- tabWidth: 4,
30
- endOfLine: 'crlf'
31
- }
32
- ],
33
- // Sort imported members while declaration order is handled by import/order
34
- 'sort-imports': [
35
- 'error',
36
- {
37
- ignoreCase: false,
38
- ignoreDeclarationSort: true,
39
- ignoreMemberSort: false,
40
- memberSyntaxSortOrder: ['none', 'all', 'multiple', 'single'],
41
- allowSeparatedGroups: true
42
- }
43
- ],
44
- // Group and alphabetize import declarations: external first, then project/relative
45
- 'import/order': [
46
- 'error',
47
- {
48
- groups: [
49
- 'builtin',
50
- 'external',
51
- 'internal',
52
- 'parent',
53
- 'sibling',
54
- 'index',
55
- 'object',
56
- 'type'
57
- ],
58
- pathGroupsExcludedImportTypes: ['builtin'],
59
- 'newlines-between': 'always',
60
- alphabetize: { order: 'asc', caseInsensitive: false }
61
- }
62
- ],
63
- // Enforce curly braces for all control statements and a consistent brace style
64
- curly: ['warn', 'all'],
65
- 'brace-style': ['error', '1tbs', { allowSingleLine: false }],
66
- indent: ['error', 'tab', { SwitchCase: 1, VariableDeclarator: { var: 1, let: 1, const: 1 } }],
67
- 'linebreak-style': ['error', 'windows']
68
- ,
69
- '@typescript-eslint/explicit-member-accessibility': [
70
- 'error',
71
- {
72
- accessibility: 'explicit',
73
- overrides: {
74
- constructors: 'no-public'
75
- }
76
- }
77
- ],
78
- '@typescript-eslint/naming-convention': [
79
- 'error',
80
- {
81
- selector: 'method',
82
- modifiers: ['private'],
83
- format: ['camelCase'],
84
- leadingUnderscore: 'require'
85
- },
86
- {
87
- selector: 'method',
88
- modifiers: ['public'],
89
- format: ['camelCase'],
90
- leadingUnderscore: 'forbid'
91
- }
92
- ]
93
- }
94
- }
95
- ];
package/src/cli.ts DELETED
@@ -1,162 +0,0 @@
1
- #!/usr/bin/env node
2
-
3
- import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
-
5
- import { getCreatioClientConfig } from './config-builder';
6
- import { AuthProviderType, CreatioEngineManager, CreatioServiceContext } from './creatio';
7
- import log from './log';
8
- import { Server } from './server';
9
- import { envBool } from './utils';
10
-
11
- type CliOptions = Record<string, string>;
12
-
13
- interface RuntimeState {
14
- server?: Server;
15
- }
16
-
17
- function printHelp(): void {
18
- const text = `
19
- MCP Creatio CLI
20
-
21
- Usage:
22
- mcp-creatio [options]
23
-
24
- Options:
25
- --base-url <url> Creatio base URL
26
- --url <url> Alias for --base-url
27
- --login <value> Creatio login (legacy auth)
28
- --password <value> Creatio password (legacy auth)
29
- --client-id <value> OAuth2 client credentials client_id
30
- --client-secret <value> OAuth2 client credentials client_secret
31
- --id-base-url <url> Creatio Identity base URL
32
- --readonly <true|false> Enable readonly mode
33
- --log-level <silent|error|warn|info>
34
- Log verbosity (default: silent)
35
- -h, --help Show this help
36
-
37
- Examples:
38
- mcp-creatio --base-url https://tenant.creatio.com --login your_login --password your_password
39
- `.trim();
40
- process.stdout.write(text + '\n');
41
- }
42
-
43
- function parseArgs(argv: string[]): CliOptions {
44
- const opts: CliOptions = {};
45
- for (let i = 0; i < argv.length; i++) {
46
- const token = argv[i];
47
- if (!token || !token.startsWith('-')) {
48
- continue;
49
- }
50
-
51
- if (token === '--help' || token === '-h') {
52
- opts.help = 'true';
53
- continue;
54
- }
55
-
56
- if (!token.startsWith('--')) {
57
- continue;
58
- }
59
-
60
- const eqIndex = token.indexOf('=');
61
- if (eqIndex > 2) {
62
- const key = token.slice(2, eqIndex);
63
- const value = token.slice(eqIndex + 1);
64
- opts[key] = value;
65
- continue;
66
- }
67
-
68
- const key = token.slice(2);
69
- const next = argv[i + 1];
70
- if (next && !next.startsWith('-')) {
71
- opts[key] = next;
72
- i++;
73
- continue;
74
- }
75
-
76
- opts[key] = 'true';
77
- }
78
- return opts;
79
- }
80
-
81
- function setEnvIfDefined(name: string, value?: string): void {
82
- if (typeof value === 'string' && value.length > 0) {
83
- process.env[name] = value;
84
- }
85
- }
86
-
87
- function applyCliEnv(opts: CliOptions): void {
88
- setEnvIfDefined('CREATIO_BASE_URL', opts['base-url'] || opts.url);
89
- setEnvIfDefined('CREATIO_LOGIN', opts.login);
90
- setEnvIfDefined('CREATIO_PASSWORD', opts.password);
91
- setEnvIfDefined('CREATIO_CLIENT_ID', opts['client-id']);
92
- setEnvIfDefined('CREATIO_CLIENT_SECRET', opts['client-secret']);
93
- setEnvIfDefined('CREATIO_ID_BASE_URL', opts['id-base-url']);
94
- setEnvIfDefined('READONLY_MODE', opts.readonly);
95
- setEnvIfDefined('MCP_CREATIO_LOG_LEVEL', opts['log-level']);
96
- }
97
-
98
- async function startStdio(server: Server): Promise<void> {
99
- const mcp = await server.startMcp();
100
- const transport = new StdioServerTransport();
101
- await mcp.connect(transport);
102
- log.info('stdio.server.start');
103
- }
104
-
105
- let shuttingDown = false;
106
-
107
- async function shutdown(signal: string, state: RuntimeState): Promise<void> {
108
- if (shuttingDown) {
109
- return;
110
- }
111
- shuttingDown = true;
112
- log.appStop({ reason: signal || 'shutdown' });
113
- try {
114
- await state.server?.stopMcp();
115
- } catch (err) {
116
- log.error('shutdown.error', { error: String(err) });
117
- }
118
- }
119
-
120
- async function main(): Promise<void> {
121
- const opts = parseArgs(process.argv.slice(2));
122
- if (opts.help === 'true') {
123
- printHelp();
124
- return;
125
- }
126
-
127
- log.useStderrOnlyLogs();
128
- applyCliEnv(opts);
129
- const cfg = getCreatioClientConfig();
130
-
131
- if (cfg.auth.kind === AuthProviderType.OAuth2Code) {
132
- throw new Error(
133
- 'oauth2_code_requires_http_server: use "npm start" (HTTP /mcp mode) for OAuth2 authorization-code flow',
134
- );
135
- }
136
-
137
- const provider = new CreatioServiceContext(cfg);
138
- const engines = new CreatioEngineManager(provider);
139
- const server = new Server(engines, { readonlyMode: envBool('READONLY_MODE', false) });
140
- const state: RuntimeState = { server };
141
-
142
- process.on('SIGINT', () => {
143
- void shutdown('SIGINT', state).finally(() => process.exit(0));
144
- });
145
- process.on('SIGTERM', () => {
146
- void shutdown('SIGTERM', state).finally(() => process.exit(0));
147
- });
148
-
149
- log.appStart({
150
- env: {
151
- node: process.version,
152
- transport: 'stdio',
153
- },
154
- });
155
-
156
- await startStdio(server);
157
- }
158
-
159
- main().catch((err) => {
160
- log.error('startup.error', { error: String(err) });
161
- process.exit(1);
162
- });
@@ -1,76 +0,0 @@
1
- import {
2
- AuthProviderType,
3
- CreatioClientAuthConfig,
4
- CreatioClientConfig,
5
- LegacyAuthConfig,
6
- OAuth2AuthConfig,
7
- OAuth2CodeAuthConfig,
8
- } from './creatio';
9
- import { env } from './utils';
10
-
11
- function getCreatioClientAuthConfig(): CreatioClientAuthConfig {
12
- const codeConf = _getOAuth2CodeAuthConfig();
13
- if (codeConf) {
14
- return codeConf;
15
- }
16
- const oauth2Conf = _getOAuth2AuthConfig();
17
- if (oauth2Conf) {
18
- return oauth2Conf;
19
- }
20
- const legacyConf = _getLegacyAuthConfig();
21
- if (legacyConf) {
22
- return legacyConf;
23
- }
24
- throw new Error(
25
- 'You must set either CREATIO_CODE_* (client id, client secret, redirect, scope) or CREATIO_CLIENT_ID/CREATIO_CLIENT_SECRET, or both CREATIO_LOGIN and CREATIO_PASSWORD',
26
- );
27
- }
28
-
29
- function _getOAuth2CodeAuthConfig(): OAuth2CodeAuthConfig | null {
30
- const codeClientId = env('CREATIO_CODE_CLIENT_ID');
31
- const codeClientSecret = env('CREATIO_CODE_CLIENT_SECRET');
32
- const codeRedirectUri = env('CREATIO_CODE_REDIRECT_URI');
33
- const codeScope = env('CREATIO_CODE_SCOPE');
34
- if (codeClientId && codeClientSecret && codeRedirectUri && codeScope) {
35
- return {
36
- kind: AuthProviderType.OAuth2Code,
37
- clientId: codeClientId,
38
- clientSecret: codeClientSecret,
39
- redirectUri: codeRedirectUri,
40
- scope: codeScope,
41
- };
42
- }
43
- return null;
44
- }
45
-
46
- function _getOAuth2AuthConfig(): OAuth2AuthConfig | null {
47
- const clientId = env('CREATIO_CLIENT_ID');
48
- const clientSecret = env('CREATIO_CLIENT_SECRET');
49
- if (clientId && clientSecret) {
50
- const conf: OAuth2AuthConfig = { kind: AuthProviderType.OAuth2, clientId, clientSecret };
51
- const idb = env('CREATIO_ID_BASE_URL');
52
- if (idb) {
53
- conf.idBaseUrl = idb;
54
- }
55
- return conf;
56
- }
57
- return null;
58
- }
59
-
60
- function _getLegacyAuthConfig(): LegacyAuthConfig | null {
61
- const login = env('CREATIO_LOGIN');
62
- const password = env('CREATIO_PASSWORD');
63
- if (login && password) {
64
- return { kind: AuthProviderType.Legacy, login, password };
65
- }
66
- return null;
67
- }
68
-
69
- export function getCreatioClientConfig(): CreatioClientConfig {
70
- const baseUrl = env('CREATIO_BASE_URL');
71
- if (!baseUrl) {
72
- throw new Error('Environment variable CREATIO_BASE_URL is required but not set');
73
- }
74
- const auth = getCreatioClientAuthConfig();
75
- return { baseUrl, auth };
76
- }
package/src/consts.ts DELETED
@@ -1,3 +0,0 @@
1
- import { env } from './utils';
2
-
3
- export const HTTP_MCP_PORT = Number(env('PORT')) || 3000;
@@ -1,27 +0,0 @@
1
- import { CreatioClientConfig } from '../client-config';
2
-
3
- import { ICreatioAuthProvider } from './auth';
4
- import { AuthProviderType, LegacyProvider, OAuth2CodeProvider, OAuth2Provider } from './providers';
5
-
6
- export class CreatioAuthManager {
7
- private readonly _config: CreatioClientConfig;
8
- private readonly _provider: ICreatioAuthProvider;
9
-
10
- constructor(config: CreatioClientConfig) {
11
- this._config = config;
12
- const authKind = this._config.auth.kind;
13
- if (authKind === AuthProviderType.OAuth2) {
14
- this._provider = new OAuth2Provider(this._config);
15
- } else if (authKind === AuthProviderType.OAuth2Code) {
16
- this._provider = new OAuth2CodeProvider(this._config);
17
- } else if (authKind === AuthProviderType.Legacy) {
18
- this._provider = new LegacyProvider(this._config);
19
- } else {
20
- throw new Error('unsupported_auth_config');
21
- }
22
- }
23
-
24
- public getProvider(): ICreatioAuthProvider {
25
- return this._provider;
26
- }
27
- }
@@ -1,31 +0,0 @@
1
- import { AuthProviderType } from './providers';
2
-
3
- export interface ICreatioAuthProvider {
4
- type: AuthProviderType;
5
- getHeaders(accept: string, isJson?: boolean): Promise<Record<string, string>>;
6
- refresh(): Promise<void>;
7
- revoke(): Promise<void>;
8
- getAuthorizeUrl(state: string): Promise<string>;
9
- finishAuthorization(code: string): Promise<void>;
10
- }
11
-
12
- export function buildHeaders(
13
- accept: string,
14
- isJson?: boolean,
15
- token?: string,
16
- ): Record<string, string> {
17
- const headers: Record<string, string> = { Accept: accept };
18
- if (isJson) {
19
- headers['Content-Type'] = 'application/json';
20
- }
21
- if (token) {
22
- headers['Authorization'] = `Bearer ${token}`;
23
- }
24
- return headers;
25
- }
26
-
27
- export const TOKEN_ENDPOINT = '/connect/token';
28
- export const AUTHORIZE_ENDPOINT = '/connect/authorize';
29
- export const REVOCATION_ENDPOINT = '/connect/revocation';
30
- export const TOKEN_BODY_SNIPPET_MAX = 1024;
31
- export const EXPIRES_MARGIN_SECONDS = 30;
@@ -1,3 +0,0 @@
1
- export * from './auth-manager';
2
- export type { ICreatioAuthProvider } from './auth';
3
- export { AuthProviderType } from './providers/type';