@signalwire/sdk 2.0.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 (325) hide show
  1. package/.github/workflows/publish.yml +27 -0
  2. package/.github/workflows/test.yml +17 -0
  3. package/CLAUDE.md +112 -0
  4. package/README.md +254 -0
  5. package/docs/MIGRATION-2.0.md +81 -0
  6. package/docs/agent-guide.md +869 -0
  7. package/docs/agent_guide.md +1026 -0
  8. package/docs/api-reference.md +2420 -0
  9. package/docs/api_reference.md +1301 -0
  10. package/docs/architecture.md +843 -0
  11. package/docs/cli-guide.md +579 -0
  12. package/docs/cli_guide.md +448 -0
  13. package/docs/cloud_functions_guide.md +474 -0
  14. package/docs/configuration.md +422 -0
  15. package/docs/contexts-guide.md +787 -0
  16. package/docs/contexts_guide.md +511 -0
  17. package/docs/datamap-guide.md +1141 -0
  18. package/docs/datamap_guide.md +595 -0
  19. package/docs/llm_parameters.md +239 -0
  20. package/docs/mcp_gateway_reference.md +648 -0
  21. package/docs/mcp_integration.md +108 -0
  22. package/docs/prefabs-guide.md +800 -0
  23. package/docs/sdk_features.md +477 -0
  24. package/docs/security.md +436 -0
  25. package/docs/serverless-guide.md +513 -0
  26. package/docs/skills-guide.md +857 -0
  27. package/docs/skills-system.md +301 -0
  28. package/docs/skills_parameter_schema.md +392 -0
  29. package/docs/skills_system.md +467 -0
  30. package/docs/swaig-reference.md +1627 -0
  31. package/docs/swaig_reference.md +910 -0
  32. package/docs/swml_service_guide.md +600 -0
  33. package/docs/third_party_skills.md +533 -0
  34. package/docs/web_service.md +677 -0
  35. package/examples/README.md +131 -0
  36. package/examples/advanced-datamap.ts +100 -0
  37. package/examples/advanced-dynamic-config.ts +70 -0
  38. package/examples/auto-vivified.ts +94 -0
  39. package/examples/call-flow.ts +63 -0
  40. package/examples/comprehensive-dynamic.ts +125 -0
  41. package/examples/contexts-steps.ts +65 -0
  42. package/examples/custom-path.ts +45 -0
  43. package/examples/datamap-tools.ts +55 -0
  44. package/examples/datasphere-multi-instance.ts +63 -0
  45. package/examples/datasphere-serverless-env.ts +68 -0
  46. package/examples/datasphere-webhook-env.ts +66 -0
  47. package/examples/datasphere.ts +37 -0
  48. package/examples/declarative.ts +100 -0
  49. package/examples/dynamic-config.ts +54 -0
  50. package/examples/dynamic-info-gatherer.ts +69 -0
  51. package/examples/dynamic-swml-service.ts +67 -0
  52. package/examples/gather-info.ts +71 -0
  53. package/examples/gather-per-question-functions-demo.ts +140 -0
  54. package/examples/joke-agent.ts +34 -0
  55. package/examples/kubernetes-agent.ts +45 -0
  56. package/examples/llm-params.ts +69 -0
  57. package/examples/mcp-agent.ts +84 -0
  58. package/examples/mcp-gateway.ts +35 -0
  59. package/examples/multi-agent.ts +73 -0
  60. package/examples/multi-endpoint.ts +79 -0
  61. package/examples/pom-prompt.ts +71 -0
  62. package/examples/prefab-concierge.ts +47 -0
  63. package/examples/prefab-faq.ts +54 -0
  64. package/examples/prefab-info-gatherer.ts +33 -0
  65. package/examples/prefab-receptionist.ts +36 -0
  66. package/examples/prefab-survey.ts +68 -0
  67. package/examples/record-call.ts +67 -0
  68. package/examples/relay-demo.ts +33 -0
  69. package/examples/room-and-sip.ts +94 -0
  70. package/examples/serverless-lambda.ts +35 -0
  71. package/examples/session-state.ts +83 -0
  72. package/examples/simple-agent.ts +36 -0
  73. package/examples/simple-static.ts +29 -0
  74. package/examples/skills-demo.ts +38 -0
  75. package/examples/step-function-inheritance-demo.ts +124 -0
  76. package/examples/swaig-features.ts +187 -0
  77. package/examples/swml-service-routing.ts +66 -0
  78. package/examples/swml-service.ts +38 -0
  79. package/examples/tap.ts +68 -0
  80. package/examples/verb-methods.ts +45 -0
  81. package/examples/web-search-multi-instance.ts +72 -0
  82. package/examples/web-search.ts +38 -0
  83. package/examples/wikipedia.ts +36 -0
  84. package/livewire/README.md +140 -0
  85. package/livewire/docs/migration-guide.md +228 -0
  86. package/livewire/examples/livewire-basic-agent.ts +74 -0
  87. package/livewire/examples/livewire-handoff.ts +197 -0
  88. package/livewire/examples/livewire-multi-tool.ts +117 -0
  89. package/package.json +38 -0
  90. package/relay/README.md +70 -0
  91. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
  92. package/relay/docs/call-methods.md +474 -0
  93. package/relay/docs/client-reference.md +142 -0
  94. package/relay/docs/events.md +134 -0
  95. package/relay/docs/getting-started.md +134 -0
  96. package/relay/docs/guide.md +306 -0
  97. package/relay/docs/messaging.md +182 -0
  98. package/relay/examples/relay-inbound.ts +66 -0
  99. package/relay/examples/relay-messaging.ts +71 -0
  100. package/relay/examples/relay-outbound.ts +76 -0
  101. package/rest/README.md +95 -0
  102. package/rest/docs/calling.md +273 -0
  103. package/rest/docs/client-reference.md +107 -0
  104. package/rest/docs/compat.md +204 -0
  105. package/rest/docs/fabric.md +183 -0
  106. package/rest/docs/getting-started.md +110 -0
  107. package/rest/docs/guide.md +351 -0
  108. package/rest/docs/namespaces.md +285 -0
  109. package/rest/examples/rest-10dlc-registration.ts +161 -0
  110. package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
  111. package/rest/examples/rest-calling-play-and-record.ts +91 -0
  112. package/rest/examples/rest-client.ts +65 -0
  113. package/rest/examples/rest-compat-laml.ts +210 -0
  114. package/rest/examples/rest-datasphere-search.ts +82 -0
  115. package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
  116. package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
  117. package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
  118. package/rest/examples/rest-manage-resources.ts +65 -0
  119. package/rest/examples/rest-phone-number-management.ts +197 -0
  120. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  121. package/rest/examples/rest-video-rooms.ts +186 -0
  122. package/src/AgentBase.ts +2489 -0
  123. package/src/AgentServer.ts +415 -0
  124. package/src/AuthHandler.ts +256 -0
  125. package/src/ConfigLoader.ts +447 -0
  126. package/src/ContextBuilder.ts +1150 -0
  127. package/src/DataMap.ts +449 -0
  128. package/src/FunctionResult.ts +866 -0
  129. package/src/Logger.ts +337 -0
  130. package/src/PomBuilder.ts +439 -0
  131. package/src/PromptManager.ts +133 -0
  132. package/src/SWMLHandler.ts +298 -0
  133. package/src/SWMLService.ts +717 -0
  134. package/src/SchemaUtils.ts +361 -0
  135. package/src/SecurityUtils.ts +153 -0
  136. package/src/ServerlessAdapter.ts +221 -0
  137. package/src/SessionManager.ts +311 -0
  138. package/src/SslConfig.ts +118 -0
  139. package/src/SwaigFunction.ts +276 -0
  140. package/src/SwmlBuilder.ts +258 -0
  141. package/src/SwmlVerbMethods.generated.ts +234 -0
  142. package/src/TypeInference.ts +181 -0
  143. package/src/WebService.ts +619 -0
  144. package/src/cli/agent-loader.ts +166 -0
  145. package/src/cli/mock-data.ts +111 -0
  146. package/src/cli/swaig-test.ts +452 -0
  147. package/src/generateVerbTypes.ts +322 -0
  148. package/src/index.ts +167 -0
  149. package/src/livewire/index.ts +950 -0
  150. package/src/prefabs/ConciergeAgent.ts +287 -0
  151. package/src/prefabs/FAQBotAgent.ts +384 -0
  152. package/src/prefabs/InfoGathererAgent.ts +339 -0
  153. package/src/prefabs/ReceptionistAgent.ts +366 -0
  154. package/src/prefabs/SurveyAgent.ts +646 -0
  155. package/src/prefabs/index.ts +27 -0
  156. package/src/relay/Action.ts +314 -0
  157. package/src/relay/Call.ts +854 -0
  158. package/src/relay/Deferred.ts +71 -0
  159. package/src/relay/Message.ts +148 -0
  160. package/src/relay/RelayClient.ts +1036 -0
  161. package/src/relay/RelayError.ts +14 -0
  162. package/src/relay/RelayEvent.ts +892 -0
  163. package/src/relay/constants.ts +132 -0
  164. package/src/relay/index.ts +123 -0
  165. package/src/relay/types.ts +149 -0
  166. package/src/rest/HttpClient.ts +103 -0
  167. package/src/rest/RestError.ts +31 -0
  168. package/src/rest/base/BaseResource.ts +19 -0
  169. package/src/rest/base/CrudResource.ts +51 -0
  170. package/src/rest/base/CrudWithAddresses.ts +26 -0
  171. package/src/rest/index.ts +200 -0
  172. package/src/rest/namespaces/addresses.ts +32 -0
  173. package/src/rest/namespaces/calling.ts +187 -0
  174. package/src/rest/namespaces/chat.ts +20 -0
  175. package/src/rest/namespaces/compat.ts +352 -0
  176. package/src/rest/namespaces/datasphere.ts +45 -0
  177. package/src/rest/namespaces/fabric.ts +222 -0
  178. package/src/rest/namespaces/imported-numbers.ts +20 -0
  179. package/src/rest/namespaces/logs.ts +84 -0
  180. package/src/rest/namespaces/lookup.ts +21 -0
  181. package/src/rest/namespaces/mfa.ts +30 -0
  182. package/src/rest/namespaces/number-groups.ts +38 -0
  183. package/src/rest/namespaces/phone-numbers.ts +44 -0
  184. package/src/rest/namespaces/project.ts +36 -0
  185. package/src/rest/namespaces/pubsub.ts +20 -0
  186. package/src/rest/namespaces/queues.ts +33 -0
  187. package/src/rest/namespaces/recordings.ts +28 -0
  188. package/src/rest/namespaces/registry.ts +101 -0
  189. package/src/rest/namespaces/short-codes.ts +28 -0
  190. package/src/rest/namespaces/sip-profile.ts +25 -0
  191. package/src/rest/namespaces/verified-callers.ts +27 -0
  192. package/src/rest/namespaces/video.ts +165 -0
  193. package/src/rest/pagination.ts +84 -0
  194. package/src/rest/types.ts +61 -0
  195. package/src/schema.json +12250 -0
  196. package/src/skills/SkillBase.ts +547 -0
  197. package/src/skills/SkillManager.ts +415 -0
  198. package/src/skills/SkillRegistry.ts +367 -0
  199. package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
  200. package/src/skills/builtin/ask_claude.ts +241 -0
  201. package/src/skills/builtin/claude_skills.ts +978 -0
  202. package/src/skills/builtin/custom_skills.ts +312 -0
  203. package/src/skills/builtin/datasphere.ts +438 -0
  204. package/src/skills/builtin/datasphere_serverless.ts +339 -0
  205. package/src/skills/builtin/datetime.ts +130 -0
  206. package/src/skills/builtin/google_maps.ts +651 -0
  207. package/src/skills/builtin/index.ts +88 -0
  208. package/src/skills/builtin/info_gatherer.ts +405 -0
  209. package/src/skills/builtin/joke.ts +191 -0
  210. package/src/skills/builtin/math.ts +142 -0
  211. package/src/skills/builtin/mcp_gateway.ts +677 -0
  212. package/src/skills/builtin/native_vector_search.ts +901 -0
  213. package/src/skills/builtin/play_background_file.ts +358 -0
  214. package/src/skills/builtin/spider.ts +869 -0
  215. package/src/skills/builtin/swml_transfer.ts +635 -0
  216. package/src/skills/builtin/weather_api.ts +248 -0
  217. package/src/skills/builtin/web_search.ts +1074 -0
  218. package/src/skills/builtin/wikipedia_search.ts +299 -0
  219. package/src/skills/index.ts +12 -0
  220. package/src/types.ts +132 -0
  221. package/tests/AgentBase.test.ts +1093 -0
  222. package/tests/AgentServer.test.ts +126 -0
  223. package/tests/AuthHandler.test.ts +133 -0
  224. package/tests/ConfigLoader.test.ts +151 -0
  225. package/tests/ContextBuilder.test.ts +108 -0
  226. package/tests/DataMap.test.ts +367 -0
  227. package/tests/EphemeralSkillCopy.test.ts +107 -0
  228. package/tests/FunctionResult.test.ts +298 -0
  229. package/tests/GracefulShutdown.test.ts +46 -0
  230. package/tests/Logger.test.ts +420 -0
  231. package/tests/PomBuilder.test.ts +228 -0
  232. package/tests/ProxyDetection.test.ts +228 -0
  233. package/tests/SWMLService.test.ts +320 -0
  234. package/tests/SWMLVerbHandler.test.ts +523 -0
  235. package/tests/SchemaUtils.test.ts +106 -0
  236. package/tests/SchemaUtils.verb.test.ts +206 -0
  237. package/tests/SecurityUtils.test.ts +192 -0
  238. package/tests/ServerlessAdapter.test.ts +222 -0
  239. package/tests/SessionManager.test.ts +257 -0
  240. package/tests/SkillBaseFeatures.test.ts +130 -0
  241. package/tests/SkillMultiInstance.test.ts +102 -0
  242. package/tests/SkillParameterSchemas.test.ts +134 -0
  243. package/tests/SkillRegistrySchema.test.ts +84 -0
  244. package/tests/SslConfig.test.ts +97 -0
  245. package/tests/SwmlBuilder.test.ts +400 -0
  246. package/tests/TypeInference.test.ts +165 -0
  247. package/tests/VerbHandlerRegistry.test.ts +128 -0
  248. package/tests/cli/mock-data.test.ts +113 -0
  249. package/tests/cli/swaig-test.test.ts +108 -0
  250. package/tests/examples.test.ts +194 -0
  251. package/tests/fixtures/scrape-parity/README.md +53 -0
  252. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
  253. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
  254. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
  255. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
  256. package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
  257. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
  258. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
  259. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
  260. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
  261. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
  262. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
  263. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
  264. package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
  265. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
  266. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
  267. package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
  268. package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
  269. package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
  270. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
  271. package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
  272. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
  273. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
  274. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
  275. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
  276. package/tests/fixtures/scrape-parity/python_extract.py +109 -0
  277. package/tests/livewire/livewire.test.ts +780 -0
  278. package/tests/mcp.test.ts +221 -0
  279. package/tests/prefabs/prefabs.test.ts +1093 -0
  280. package/tests/relay/Action.test.ts +392 -0
  281. package/tests/relay/Call.test.ts +535 -0
  282. package/tests/relay/Deferred.test.ts +71 -0
  283. package/tests/relay/Message.test.ts +164 -0
  284. package/tests/relay/RelayClient.test.ts +779 -0
  285. package/tests/relay/RelayEvent.test.ts +463 -0
  286. package/tests/relay/helpers.ts +79 -0
  287. package/tests/rest/HttpClient.test.ts +274 -0
  288. package/tests/rest/RestError.test.ts +53 -0
  289. package/tests/rest/calling.test.ts +156 -0
  290. package/tests/rest/client.test.ts +197 -0
  291. package/tests/rest/compat.test.ts +335 -0
  292. package/tests/rest/datasphere.test.ts +71 -0
  293. package/tests/rest/fabric.test.ts +186 -0
  294. package/tests/rest/helpers.ts +95 -0
  295. package/tests/rest/logs.test.ts +68 -0
  296. package/tests/rest/pagination.test.ts +133 -0
  297. package/tests/rest/registry.test.ts +94 -0
  298. package/tests/rest/relay-rest.test.ts +290 -0
  299. package/tests/rest/video.test.ts +173 -0
  300. package/tests/setup.ts +6 -0
  301. package/tests/skills/SkillBase.test.ts +108 -0
  302. package/tests/skills/SkillManager.test.ts +268 -0
  303. package/tests/skills/SkillRegistry.test.ts +176 -0
  304. package/tests/skills/builtin.test.ts +1472 -0
  305. package/tests/skills/claude-skills.test.ts +54 -0
  306. package/tests/skills/custom-skills.test.ts +53 -0
  307. package/tests/skills/datasphere-serverless.test.ts +70 -0
  308. package/tests/skills/datasphere.test.ts +107 -0
  309. package/tests/skills/datetime.test.ts +101 -0
  310. package/tests/skills/google-maps.test.ts +78 -0
  311. package/tests/skills/info-gatherer.test.ts +411 -0
  312. package/tests/skills/joke.test.ts +81 -0
  313. package/tests/skills/math.test.ts +68 -0
  314. package/tests/skills/mcp-gateway.test.ts +101 -0
  315. package/tests/skills/play-background.test.ts +54 -0
  316. package/tests/skills/spider.test.ts +108 -0
  317. package/tests/skills/swml-transfer.test.ts +178 -0
  318. package/tests/skills/trivia.test.ts +54 -0
  319. package/tests/skills/vector-search.test.ts +135 -0
  320. package/tests/skills/weather-api.test.ts +77 -0
  321. package/tests/skills/web-search-parity.test.ts +59 -0
  322. package/tests/skills/web-search.test.ts +103 -0
  323. package/tests/skills/wikipedia.test.ts +63 -0
  324. package/tsconfig.json +18 -0
  325. package/vitest.config.ts +9 -0
@@ -0,0 +1,648 @@
1
+ # MCP to SWAIG Gateway
2
+
3
+ ## Overview
4
+
5
+ The MCP-SWAIG Gateway bridges Model Context Protocol (MCP) servers with SignalWire AI Gateway (SWAIG) functions, allowing SignalWire AI agents to interact with MCP-based tools. This gateway acts as a translation layer and session manager between the two protocols.
6
+
7
+ ## Installation
8
+
9
+ The MCP Gateway is included in the SignalWire Agents SDK. Install with the gateway dependencies:
10
+
11
+ ```bash
12
+ pip install "@signalwire/sdk[mcp-gateway]"
13
+ ```
14
+
15
+ Once installed, the `mcp-gateway` CLI command is available:
16
+
17
+ ```bash
18
+ mcp-gateway -c config.json
19
+ ```
20
+
21
+ ## Architecture
22
+
23
+ ### Components
24
+
25
+ 1. **MCP Gateway Service** (`mcp_gateway/`)
26
+ - HTTP/HTTPS server with Basic Authentication
27
+ - Manages multiple MCP server instances
28
+ - Handles session lifecycle per SignalWire call
29
+ - Translates between SWAIG and MCP protocols
30
+
31
+ 2. **MCP Gateway Skill** (`signalwire_agents/skills/mcp_gateway/`)
32
+ - SignalWire skill that connects agents to the gateway
33
+ - Dynamically creates SWAIG functions from MCP tools
34
+ - Manages session lifecycle using call_id
35
+
36
+ 3. **Test MCP Server** (`mcp_gateway/test/todo_mcp.py`)
37
+ - Simple todo list MCP server for testing
38
+ - Demonstrates stateful MCP server implementation
39
+
40
+ ## Protocol Flow
41
+
42
+ ```
43
+ SignalWire Agent Gateway Service MCP Server
44
+ | | |
45
+ |---(1) Add Skill--------------->| |
46
+ |<--(2) Query Tools--------------| |
47
+ | |---(3) List Tools-------->|
48
+ | |<--(4) Tool List----------|
49
+ |---(5) Call SWAIG Function----->| |
50
+ | |---(6) Spawn Session----->|
51
+ | |---(7) Call MCP Tool----->|
52
+ | |<--(8) MCP Response-------|
53
+ |<--(9) SWAIG Response-----------| |
54
+ | | |
55
+ |---(10) Hangup Hook------------>| |
56
+ | |---(11) Close Session---->|
57
+ ```
58
+
59
+ ## Message Envelope Format
60
+
61
+ The gateway uses a custom envelope format for routing and session management:
62
+
63
+ ```json
64
+ {
65
+ "session_id": "call_xyz123", // From SWAIG call_id
66
+ "service": "todo", // MCP service name
67
+ "tool": "add_todo", // Tool name
68
+ "arguments": { // Tool arguments
69
+ "text": "Buy milk"
70
+ },
71
+ "timeout": 300, // Session timeout in seconds
72
+ "metadata": { // Optional metadata
73
+ "agent_id": "agent_123",
74
+ "timestamp": "2024-01-20T10:30:00Z"
75
+ }
76
+ }
77
+ ```
78
+
79
+ ## Directory Structure
80
+
81
+ ```
82
+ signalwire_agents/mcp_gateway/ # Core gateway package (installed with SDK)
83
+ ├── __init__.py # Package exports
84
+ ├── gateway_service.py # Main HTTP/HTTPS server
85
+ ├── mcp_manager.py # MCP server lifecycle management
86
+ └── session_manager.py # Session handling and timeouts
87
+
88
+ mcp_gateway/ # Configuration and deployment files
89
+ ├── config.json # Gateway configuration
90
+ ├── sample_config.json # Example configuration
91
+ ├── Dockerfile # Docker container definition
92
+ ├── docker-compose.yml # Docker compose configuration
93
+ ├── mcp-docker.sh # Docker management helper script
94
+ ├── README.md # Gateway documentation
95
+ ├── certs/ # SSL certificates (optional)
96
+ │ └── .gitignore # Ignore actual certificates
97
+ ├── test/
98
+ │ ├── todo_mcp.py # Test MCP server
99
+ │ ├── test_gateway.sh # Curl test scripts
100
+ │ └── test_agent.py # Test SignalWire agent
101
+ └── examples/
102
+ └── generate_cert.sh # Generate self-signed certificate
103
+
104
+ signalwire_agents/skills/mcp_gateway/
105
+ ├── __init__.py
106
+ ├── skill.py # MCP gateway skill
107
+ └── README.md # Skill documentation
108
+ ```
109
+
110
+ ## Configuration
111
+
112
+ ### Gateway Configuration (`config.json`)
113
+
114
+ The configuration supports environment variable substitution using `${VAR_NAME|default}` syntax:
115
+
116
+ ```json
117
+ {
118
+ "server": {
119
+ "host": "${MCP_HOST|0.0.0.0}",
120
+ "port": "${MCP_PORT|8080}",
121
+ "auth_user": "${MCP_AUTH_USER|admin}",
122
+ "auth_password": "${MCP_AUTH_PASSWORD|changeme}",
123
+ "auth_token": "${MCP_AUTH_TOKEN|optional-bearer-token}"
124
+ },
125
+ "services": {
126
+ "todo": {
127
+ "command": ["python3", "./test/todo_mcp.py"],
128
+ "description": "Simple todo list for testing",
129
+ "enabled": true,
130
+ "sandbox": {
131
+ "enabled": true,
132
+ "resource_limits": true,
133
+ "restricted_env": true
134
+ }
135
+ },
136
+ "shell-mpc": {
137
+ "command": ["python3", "/path/to/shell_mpc.py"],
138
+ "description": "Shell PTY access",
139
+ "enabled": false,
140
+ "sandbox": {
141
+ "enabled": false,
142
+ "note": "Shell access needs full filesystem"
143
+ }
144
+ },
145
+ "calculator": {
146
+ "command": ["node", "/path/to/calculator.js"],
147
+ "description": "Math calculations",
148
+ "enabled": true,
149
+ "sandbox": {
150
+ "enabled": true,
151
+ "resource_limits": true,
152
+ "restricted_env": false,
153
+ "note": "Needs NODE_PATH but can have resource limits"
154
+ }
155
+ }
156
+ },
157
+ "session": {
158
+ "default_timeout": 300,
159
+ "max_sessions_per_service": 100,
160
+ "cleanup_interval": 60,
161
+ "sandbox_dir": "./sandbox"
162
+ },
163
+ "rate_limiting": {
164
+ "default_limits": ["200 per day", "50 per hour"],
165
+ "tools_limit": "30 per minute",
166
+ "call_limit": "10 per minute",
167
+ "session_delete_limit": "20 per minute",
168
+ "storage_uri": "memory://"
169
+ },
170
+ "logging": {
171
+ "level": "INFO",
172
+ "file": "gateway.log"
173
+ }
174
+ }
175
+ ```
176
+
177
+ ### Environment Variable Substitution
178
+
179
+ The gateway supports environment variable substitution in config.json using the format `${VAR_NAME|default_value}`.
180
+
181
+ Example usage:
182
+
183
+ **Method 1: Using .env file (recommended)**
184
+ ```bash
185
+ # Copy the example
186
+ cp .env.example .env
187
+
188
+ # Edit with your values
189
+ vim .env
190
+
191
+ # Run - Docker Compose automatically reads .env
192
+ ./mcp-docker.sh start
193
+
194
+ # Or for non-Docker
195
+ source .env
196
+ python3 gateway_service.py
197
+ ```
198
+
199
+ **Method 2: Export environment variables**
200
+ ```bash
201
+ # Set environment variables
202
+ export MCP_PORT=9000
203
+ export MCP_AUTH_PASSWORD=mysecret
204
+
205
+ # Run the gateway
206
+ python3 gateway_service.py
207
+ ```
208
+
209
+ **Method 3: Inline variables**
210
+ ```bash
211
+ # Set variables for just this command
212
+ MCP_PORT=9000 MCP_AUTH_PASSWORD=mysecret ./mcp-docker.sh start
213
+ ```
214
+
215
+ Supported variables:
216
+ - `MCP_HOST`: Server bind address (default: 0.0.0.0)
217
+ - `MCP_PORT`: Server port (default: 8080)
218
+ - `MCP_AUTH_USER`: Basic auth username (default: admin)
219
+ - `MCP_AUTH_PASSWORD`: Basic auth password (default: changeme)
220
+ - `MCP_AUTH_TOKEN`: Bearer token for API access (default: empty)
221
+ - `MCP_SESSION_TIMEOUT`: Session timeout in seconds (default: 300)
222
+ - `MCP_MAX_SESSIONS`: Max sessions per service (default: 100)
223
+ - `MCP_CLEANUP_INTERVAL`: Session cleanup interval in seconds (default: 60)
224
+ - `MCP_LOG_LEVEL`: Logging level (default: INFO)
225
+ - `MCP_LOG_FILE`: Log file path (default: gateway.log)
226
+
227
+ ### Sandbox Configuration Options
228
+
229
+ Each service can have its own sandbox configuration:
230
+
231
+ | Option | Default | Description |
232
+ |--------|---------|-------------|
233
+ | `enabled` | `true` | Enable/disable sandboxing completely |
234
+ | `resource_limits` | `true` | Apply CPU, memory, process limits |
235
+ | `restricted_env` | `true` | Use minimal environment variables |
236
+ | `working_dir` | Current dir | Working directory for the process |
237
+ | `allowed_paths` | N/A | Future: Path access restrictions |
238
+
239
+ #### Sandbox Profiles
240
+
241
+ 1. **High Security** (Default)
242
+ ```json
243
+ "sandbox": {
244
+ "enabled": true,
245
+ "resource_limits": true,
246
+ "restricted_env": true
247
+ }
248
+ ```
249
+
250
+ 2. **Medium Security** (For services needing env vars)
251
+ ```json
252
+ "sandbox": {
253
+ "enabled": true,
254
+ "resource_limits": true,
255
+ "restricted_env": false
256
+ }
257
+ ```
258
+
259
+ 3. **No Sandbox** (For trusted services needing full access)
260
+ ```json
261
+ "sandbox": {
262
+ "enabled": false
263
+ }
264
+ ```
265
+
266
+ ### Skill Configuration
267
+
268
+ ```python
269
+ agent.add_skill("mcp_gateway", {
270
+ "gateway_url": "https://localhost:8080",
271
+ "auth_user": "admin",
272
+ "auth_password": "changeme",
273
+ "services": [
274
+ {
275
+ "name": "todo",
276
+ "tools": ["add_todo", "list_todos"] # Specific tools only
277
+ },
278
+ {
279
+ "name": "calculator",
280
+ "tools": "*" # All tools
281
+ }
282
+ ],
283
+ "session_timeout": 300, # Override default timeout
284
+ "tool_prefix": "mcp_", # Prefix for SWAIG function names
285
+ "retry_attempts": 3, # Gateway connection retries
286
+ "request_timeout": 30, # Individual request timeout
287
+ "verify_ssl": True # SSL certificate verification
288
+ })
289
+ ```
290
+
291
+ ## API Endpoints
292
+
293
+ ### Gateway Service Endpoints
294
+
295
+ #### GET /health
296
+ Health check endpoint
297
+ ```bash
298
+ curl http://localhost:8080/health
299
+ ```
300
+
301
+ #### GET /services
302
+ List available MCP services
303
+ ```bash
304
+ curl -u admin:changeme http://localhost:8080/services
305
+ ```
306
+
307
+ #### GET /services/{service_name}/tools
308
+ Get tools for a specific service
309
+ ```bash
310
+ curl -u admin:changeme http://localhost:8080/services/todo/tools
311
+ ```
312
+
313
+ #### POST /services/{service_name}/call
314
+ Call a tool on a service
315
+
316
+ Using Basic Auth:
317
+ ```bash
318
+ curl -u admin:changeme -X POST http://localhost:8080/services/todo/call \
319
+ -H "Content-Type: application/json" \
320
+ -d '{
321
+ "tool": "add_todo",
322
+ "arguments": {"text": "Test item"},
323
+ "session_id": "test-123",
324
+ "timeout": 300
325
+ }'
326
+ ```
327
+
328
+ Using Bearer Token:
329
+ ```bash
330
+ curl -X POST http://localhost:8080/services/todo/call \
331
+ -H "Authorization: Bearer your-token-here" \
332
+ -H "Content-Type: application/json" \
333
+ -d '{
334
+ "tool": "add_todo",
335
+ "arguments": {"text": "Test item"},
336
+ "session_id": "test-123"
337
+ }'
338
+ ```
339
+
340
+ #### GET /sessions
341
+ List active sessions
342
+ ```bash
343
+ curl -u admin:changeme http://localhost:8080/sessions
344
+ ```
345
+
346
+ #### DELETE /sessions/{session_id}
347
+ Close a specific session
348
+ ```bash
349
+ curl -u admin:changeme -X DELETE http://localhost:8080/sessions/test-123
350
+ ```
351
+
352
+ ## Security Features
353
+
354
+ ### Authentication
355
+ - **Basic Auth**: Username/password authentication
356
+ - **Bearer Token**: Alternative token-based authentication
357
+ - **Dual Support**: Can use either Basic Auth or Bearer tokens
358
+
359
+ ### Input Validation
360
+ - Service name validation (alphanumeric + dash/underscore, max 64 chars)
361
+ - Session ID validation (alphanumeric + dot/dash/underscore, max 128 chars)
362
+ - Tool name validation (alphanumeric + dash/underscore, max 64 chars)
363
+ - Request size limits (10MB max)
364
+
365
+ ### Rate Limiting
366
+ Fully configurable through the `rate_limiting` section in config.json:
367
+
368
+ ```json
369
+ "rate_limiting": {
370
+ "default_limits": ["200 per day", "50 per hour"],
371
+ "tools_limit": "30 per minute",
372
+ "call_limit": "10 per minute",
373
+ "session_delete_limit": "20 per minute",
374
+ "storage_uri": "memory://"
375
+ }
376
+ ```
377
+
378
+ - `default_limits`: Global rate limits per IP address
379
+ - `tools_limit`: Rate limit for `/services/*/tools` endpoints
380
+ - `call_limit`: Rate limit for `/services/*/call` endpoints
381
+ - `session_delete_limit`: Rate limit for session deletion
382
+ - `storage_uri`: Storage backend for rate limit counters (memory:// or redis://)
383
+
384
+ ### Security Headers
385
+ - X-Content-Type-Options: nosniff
386
+ - X-Frame-Options: DENY
387
+ - X-XSS-Protection: 1; mode=block
388
+ - Content-Security-Policy: default-src 'none'
389
+ - Strict-Transport-Security (HTTPS only)
390
+
391
+ ### Process Sandboxing
392
+ Configurable per MCP service with three security levels:
393
+
394
+ 1. **High Security** (Default)
395
+ - Process isolation with resource limits
396
+ - Restricted environment variables
397
+ - CPU time: 300s, Memory: 512MB, Processes: 10
398
+ - File size: 10MB max
399
+
400
+ 2. **Medium Security**
401
+ - Resource limits enabled
402
+ - Full environment variables
403
+ - For services needing PATH, NODE_PATH, etc.
404
+
405
+ 3. **No Sandbox**
406
+ - Disabled sandboxing for trusted services
407
+ - Full filesystem and resource access
408
+
409
+ ### Other Security Features
410
+ - HTTPS support with SSL/TLS
411
+ - Session isolation between calls
412
+ - Automatic session cleanup
413
+ - Security event logging
414
+ - Dangerous environment variable filtering
415
+
416
+ ## Testing
417
+
418
+ ### 1. Unit Testing the Gateway
419
+
420
+ ```bash
421
+ # Start the gateway
422
+ cd mcp_gateway
423
+ python3 gateway_service.py
424
+
425
+ # Test with curl
426
+ ./test/test_gateway.sh
427
+ ```
428
+
429
+ ### 2. Testing with SWAIG CLI
430
+
431
+ ```bash
432
+ # Test the agent with MCP skill
433
+ swaig-test test/test_agent.py --list-tools
434
+
435
+ # IMPORTANT: --call-id must come BEFORE --exec for session persistence
436
+ swaig-test test/test_agent.py --call-id test-session --exec mcp_todo_add_todo --text "Buy milk"
437
+ swaig-test test/test_agent.py --call-id test-session --exec mcp_todo_list_todos
438
+
439
+ # WRONG: This won't work - --call-id after --exec is treated as function argument
440
+ swaig-test test/test_agent.py --exec mcp_todo_add_todo --text "Buy milk" --call-id test-session
441
+
442
+ # Generate SWML document
443
+ swaig-test test/test_agent.py --dump-swml
444
+ ```
445
+
446
+ ### 3. End-to-End Testing
447
+
448
+ ```python
449
+ # test/test_agent.py
450
+ from signalwire_agents import AgentBase
451
+
452
+ class TestMCPAgent(AgentBase):
453
+ def __init__(self):
454
+ super().__init__(name="MCP Test Agent")
455
+
456
+ self.add_skill("mcp_gateway", {
457
+ "gateway_url": "http://localhost:8080",
458
+ "auth_user": "admin",
459
+ "auth_password": "changeme",
460
+ "services": [{"name": "todo"}]
461
+ })
462
+
463
+ if __name__ == "__main__":
464
+ agent = TestMCPAgent()
465
+ agent.run()
466
+ ```
467
+
468
+ ## Deployment
469
+
470
+ ### Local Development
471
+ ```bash
472
+ cd mcp_gateway
473
+ python3 gateway_service.py
474
+ ```
475
+
476
+ ### Docker Deployment
477
+
478
+ #### Configuration Options
479
+ The Docker setup supports three configuration scenarios:
480
+
481
+ 1. **Runtime Config** (highest priority): Mount config.json at runtime
482
+ 2. **Build-time Config**: Include config.json when building the image
483
+ 3. **Default Config**: Falls back to sample_config.json
484
+
485
+ To pre-configure the image at build time:
486
+ ```bash
487
+ # Edit your config.json
488
+ cp sample_config.json config.json
489
+ vim config.json
490
+
491
+ # Build with config included
492
+ ./mcp-docker.sh build # Will include config.json in image
493
+ ```
494
+
495
+ **Port Configuration**: The Docker setup automatically reads the port from your config.json file. If your config specifies port 8100, Docker will expose the service on port 8100.
496
+
497
+ The mcp-docker.sh script automatically detects the port from config.json. You can also override it using an environment variable:
498
+ ```bash
499
+ # Override port at runtime (must match what's in config.json)
500
+ MCP_PORT=8100 ./mcp-docker.sh start
501
+ ```
502
+
503
+ Note: The port in the MCP_PORT environment variable should match the port configured in your config.json file, as the container internally listens on the configured port.
504
+
505
+ #### Using mcp-docker.sh Helper Script
506
+ The easiest way to manage the Docker deployment is using the provided helper script:
507
+
508
+ ```bash
509
+ cd mcp_gateway
510
+
511
+ # Show available commands
512
+ ./mcp-docker.sh help
513
+
514
+ # Build the Docker image
515
+ ./mcp-docker.sh build
516
+
517
+ # Start in foreground (Ctrl+C to stop)
518
+ ./mcp-docker.sh start
519
+
520
+ # Start in background
521
+ ./mcp-docker.sh start -d
522
+
523
+ # View logs
524
+ ./mcp-docker.sh logs
525
+ ./mcp-docker.sh logs -f # Follow logs
526
+
527
+ # Check status
528
+ ./mcp-docker.sh status
529
+
530
+ # Restart the container
531
+ ./mcp-docker.sh restart
532
+
533
+ # Stop the container
534
+ ./mcp-docker.sh stop
535
+
536
+ # Open shell in running container
537
+ ./mcp-docker.sh shell
538
+
539
+ # Clean up (remove container and volumes)
540
+ ./mcp-docker.sh clean
541
+ ```
542
+
543
+ #### Manual Docker Commands
544
+ ```bash
545
+ cd mcp_gateway
546
+ docker build -t mcp-gateway .
547
+ docker run -p 8080:8080 -v $(pwd)/config.json:/app/config.json mcp-gateway
548
+ ```
549
+
550
+ #### Docker Compose
551
+ ```bash
552
+ cd mcp_gateway
553
+ docker-compose up
554
+ docker-compose up -d # Run in background
555
+ docker-compose logs -f # Follow logs
556
+ docker-compose down # Stop and remove
557
+ ```
558
+
559
+ ### Production with HTTPS
560
+ ```bash
561
+ # Generate or place certificates
562
+ mkdir -p certs
563
+ # Place server.pem in certs/
564
+
565
+ # Run with HTTPS
566
+ python3 gateway_service.py
567
+ ```
568
+
569
+ ## Implementation Details
570
+
571
+ ### Session Management
572
+
573
+ 1. **Session Creation**: First tool call creates session with call_id
574
+ 2. **Session Persistence**: Sessions maintained across multiple tool calls
575
+ 3. **Session Cleanup**: Automatic cleanup on timeout or hangup hook
576
+ 4. **State Isolation**: Each session gets separate MCP server instance
577
+
578
+ ### Error Handling
579
+
580
+ 1. **MCP Server Failures**: Automatic restart with backoff
581
+ 2. **Network Errors**: Retry logic with configurable attempts
582
+ 3. **Invalid Requests**: Clear error messages returned to SWAIG
583
+ 4. **Resource Exhaustion**: Reject new sessions when at limit
584
+
585
+ ### Performance Optimization
586
+
587
+ 1. **Connection Pooling**: Reuse HTTP connections to gateway
588
+ 2. **Lazy Loading**: MCP servers started only when needed
589
+ 3. **Efficient Cleanup**: Background thread for session management
590
+ 4. **Response Caching**: Optional caching for read-only operations
591
+
592
+ ## Troubleshooting
593
+
594
+ ### Common Issues
595
+
596
+ 1. **MCP Server Won't Start**
597
+ - Check command path in config.json
598
+ - Verify MCP server is executable
599
+ - Check logs for import errors
600
+ - Ensure working directory is correct for sandboxed processes
601
+
602
+ 2. **Authentication Failures**
603
+ - Verify credentials match in config and skill
604
+ - Check Basic Auth header format
605
+ - For Bearer tokens, ensure "Bearer " prefix is included
606
+
607
+ 3. **Session Timeouts**
608
+ - Increase timeout in skill configuration
609
+ - Check gateway logs for premature cleanup
610
+ - Monitor for stuck MCP processes
611
+
612
+ 4. **SSL Certificate Errors**
613
+ - For self-signed certs, set `verify_ssl: false`
614
+ - Ensure cert path is correct
615
+
616
+ 5. **Gateway Shutdown Hangs**
617
+ - Fixed in latest version with improved thread management
618
+ - Ensure you're running the updated code
619
+ - Check for zombie MCP processes: `ps aux | grep mcp`
620
+
621
+ 6. **Session Persistence Issues**
622
+ - Ensure MCP process doesn't die between calls
623
+ - Check reader thread isn't creating thread leaks
624
+ - Monitor process count with `ps aux | grep todo_mcp`
625
+
626
+ ### Debug Mode
627
+
628
+ Enable debug logging:
629
+ ```json
630
+ {
631
+ "logging": {
632
+ "level": "DEBUG",
633
+ "file": "gateway.log"
634
+ }
635
+ }
636
+ ```
637
+
638
+ ## Examples
639
+
640
+ - `examples/mcp_gateway_demo.py` - Agent connecting to MCP servers through the `mcp_gateway` skill
641
+
642
+ ## Future Enhancements
643
+
644
+ 1. **WebSocket Support**: Real-time bidirectional communication
645
+ 2. **Multi-tenant**: Separate auth/permissions per tenant
646
+ 3. **Metrics/Monitoring**: Prometheus endpoints
647
+ 4. **Load Balancing**: Multiple gateway instances
648
+ 5. **Plugin System**: Custom transformations/middleware