twilio-labs · pkamp3 · May 19, 2025 · May 19, 2025 · May 19, 2025 · May 19, 2025
diff --git a/mcp-server/.env.example b/mcp-server/.env.example
@@ -0,0 +1,23 @@
+# description: Your Twilio Account SID
+# format: text
+# link: https://www.twilio.com/console
+# required: true
+ACCOUNT_SID=ACxxx
+
+# description: Your Twilio Auth Token
+# format: text
+# link: https://www.twilio.com/console
+# required: true
+AUTH_TOKEN=abc
+
+# description: Your Twilio API Key
+# format: text
+# link: https://www.twilio.com/console/project/api-keys
+# required: true
+API_KEY=SKxxx
+
+# description: Your Twilio API Secret
+# format: text
+# link: https://www.twilio.com/console/project/api-keys
+# required: true
+API_SECRET=abc
diff --git a/mcp-server/.owners b/mcp-server/.owners
@@ -0,0 +1,4 @@
+ktalebian
+vingiarrusso
+bpartridge
+# Insert your Github username here
diff --git a/mcp-server/CHANGELOG.md b/mcp-server/CHANGELOG.md
@@ -0,0 +1,8 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0]
+### Added
+- Initial release.
+
diff --git a/mcp-server/README.md b/mcp-server/README.md
@@ -0,0 +1,84 @@
+# mcp-server
+
+Functions to run a remote MCP server for Twilio API tools
+
+## Pre-requisites
+
+### Environment variables
+
+This project requires some environment variables to be set. A file named `.env` is used to store the values for those environment variables. To keep your tokens and secrets secure, make sure to not commit the `.env` file in git. When setting up the project with `twilio serverless:init ...` the Twilio CLI will create a `.gitignore` file that excludes `.env` from the version history.
+
+In your `.env` file, set the following values:
+
+* ACCOUNT_SID
+* AUTH_TOKEN
+* API_KEY
+* API_SECRET
+
+## Create a new project with the template
+
+1. Install the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart#install-twilio-cli)
+2. Install the [serverless toolkit](https://www.twilio.com/docs/labs/serverless-toolkit/getting-started)
+
+```shell
+twilio plugins:install @twilio-labs/plugin-serverless
+```
+
+3. Initiate a new project
+
+```
+twilio serverless:init example --template=mcp-server && cd example
+```
+
+4. Start the server with the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart):
+
+```
+twilio serverless:start
+```
+
+ℹ️ Check the developer console and terminal for any errors, make sure you've set your environment variables.
+
+## Deploying
+
+Deploy your functions and assets with either of the following commands. Note: you must run these commands from inside your project folder. [More details in the docs.](https://www.twilio.com/docs/labs/serverless-toolkit)
+
+With the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart):
+
+```
+twilio serverless:deploy
+```
+
+## Integration with MCP clients
+
+`https://<functions-domain>.twil.io/mcp?services=`
+
+Header: x-twilio-signature
+
+@TODO: Code samples to generate x-twilio-signature
+
+Available services
+* Messaging (default)
+* Voice
+* VoiceAddOns
+* Conversations
+* Studio
+* TaskRouter
+* Serverless
+* Account
+* PhoneNumbers
+* Applications
+* Auth
+* AddOns
+* Usage
+
+## Example prompts
+
+@TODO
+
+## Security recommendations
+
+This remote MCP server function will provide Tools to your LLM that provide access to your Twilio account. We recommend the following considerations when giving clients access to your server:
+
+- Always set the `requires_approval` field to ensure that there are no unintended actions taken within your account.
+- Use scoped permissions for your Twilio API Key. Not all endpoints support scoped permissions, but some do. See https://www.twilio.com/docs/iam/api-keys/restricted-api-keys for more information about which actions are supported per API Service.
+- To ensure privacy, do not use other MCP servers in conjunction with your Twilio MCP server.
diff --git a/mcp-server/assets/index.html b/mcp-server/assets/index.html
@@ -0,0 +1,81 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <meta http-equiv="x-ua-compatible" content="ie=edge">
+        <title>Get started with your Twilio Functions!</title>
+
+        <link rel="icon" href="https://twilio-labs.github.io/function-templates/static/v1/favicon.ico">
+        <link rel="stylesheet" href="https://twilio-labs.github.io/function-templates/static/v1/ce-paste-theme.css">
+        <script src="https://twilio-labs.github.io/function-templates/static/v1/ce-helpers.js" defer></script>
+        <script>
+         window.addEventListener('DOMContentLoaded', (_event) => {
+             inputPrependBaseURL();
+         });
+        </script>
+    </head>
+    <body>
+        <div class="page-top">
+            <header>
+                <div id="twilio-logo">
+                    <a href="https://www.twilio.com/" target="_blank" rel="noopener">
+                        <svg class="logo" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewbox="0 0 60 60">
+                            <title>Twilio Logo</title><path class="cls-1" d="M30,15A15,15,0,1,0,45,30,15,15,0,0,0,30,15Zm0,26A11,11,0,1,1,41,30,11,11,0,0,1,30,41Zm6.8-14.7a3.1,3.1,0,1,1-3.1-3.1A3.12,3.12,0,0,1,36.8,26.3Zm0,7.4a3.1,3.1,0,1,1-3.1-3.1A3.12,3.12,0,0,1,36.8,33.7Zm-7.4,0a3.1,3.1,0,1,1-3.1-3.1A3.12,3.12,0,0,1,29.4,33.7Zm0-7.4a3.1,3.1,0,1,1-3.1-3.1A3.12,3.12,0,0,1,29.4,26.3Z"/></svg>
+                    </a>
+                </div>
+                <nav>
+                    <span>Your Twilio application</span>
+                    <aside>
+                        <svg class="icon" role="img" aria-hidden="true" width="100%" height="100%" viewBox="0 0 20 20" aria-labelledby="NewIcon-1577"><path fill="currentColor" fill-rule="evenodd" d="M6.991 7.507c.003-.679 1.021-.675 1.019.004-.012 2.956 1.388 4.41 4.492 4.48.673.016.66 1.021-.013 1.019-2.898-.011-4.327 1.446-4.48 4.506-.033.658-1.01.639-1.018-.02-.03-3.027-1.382-4.49-4.481-4.486-.675 0-.682-1.009-.008-1.019 3.02-.042 4.478-1.452 4.49-4.484zm.505 2.757l-.115.242c-.459.9-1.166 1.558-2.115 1.976l.176.08c.973.465 1.664 1.211 2.083 2.22l.02.05.088-.192c.464-.973 1.173-1.685 2.123-2.124l.039-.018-.118-.05c-.963-.435-1.667-1.117-2.113-2.034l-.068-.15zm10.357-8.12c.174.17.194.434.058.625l-.058.068-1.954 1.905 1.954 1.908a.482.482 0 010 .694.512.512 0 01-.641.056l-.07-.056-1.954-1.908-1.954 1.908a.511.511 0 01-.71 0 .482.482 0 01-.058-.626l.058-.068 1.954-1.908-1.954-1.905a.482.482 0 010-.693.512.512 0 01.64-.057l.07.057 1.954 1.905 1.954-1.905a.511.511 0 01.71 0z"></path></svg>
+                        Live
+                    </aside>
+                </nav>
+            </header>
+        </div>
+        <main>
+            <div class="content">
+                <h1>
+                    <img src="https://twilio-labs.github.io/function-templates/static/v1/success.svg" />
+                    <div>
+                        <p>Welcome!</p>
+                        <p>Your remote MCP server!</p>
+                    </div>
+                </h1>
+                <section>
+                    <h2>Get started with your application</h2>
+                    <p>
+                        Follow these steps to try out your new app:
+                    </p>
+                    <ol class="steps">
+                        <li>Configure your MCP client application to use the /mcp endpoint</li>
+                        <li>Make sure you're generating a signature to pass with your requests using the `x-twilio-signature` header.</li>
+                        <li>Filter the MCP tools by passing a `?service` query parameter, using one or more of the services below.</li>
+                    </ol>
+                </section>
+                <section>
+                  <h3>Available services</h3>
+                  <ul style="list-style-type: disc; padding-left: 40px;">
+                    <li>Messaging (default)</li>
+                    <li>Voice</li>
+                    <li>VoiceAddOns</li>
+                    <li>Conversations</li>
+                    <li>Studio</li>
+                    <li>TaskRouter</li>
+                    <li>Serverless</li>
+                    <li>Account</li>
+                    <li>PhoneNumbers</li>
+                    <li>Applications</li>
+                    <li>Auth</li>
+                    <li>AddOns</li>
+                    <li>Usage</li>
+                  </ul>
+                    <!-- APP_INFO_V2 -->
+                </section>
+            </div>
+        </main>
+        <footer>
+            <span class="statement">We can't wait to see what you build.</span>
+        </footer>
+    </body>
+</html>
diff --git a/mcp-server/functions/mcp.protected.js b/mcp-server/functions/mcp.protected.js
@@ -0,0 +1,146 @@
+/* eslint-disable callback-return */
+
+const { randomUUID } = require('crypto');
+
+const modules = Runtime.getFunctions();
+const createServer = require(modules.server.path);
+const createReq = require(modules.req.path);
+const createRes = require(modules.res.path);
+
+const defaultMessaging = [
+  'Api20100401Message',
+  'Api20100401IncomingPhoneNumber',
+];
+
+const TWILIO_TAG_MAP = {
+  Messaging: defaultMessaging,
+  Voice: ['Api20100401Call'],
+  VoiceAddOns: [
+    'Api20100401Recording',
+    'Api20100401Transcription',
+    'Api20100401Conference',
+  ],
+  Conversations: [
+    'ConversationsV1Conversation',
+    'ConversationsV1Message',
+    'ConversationsV1Participant',
+    'ConversationsV1Service',
+    'ConversationsV1User',
+  ],
+  Studio: [
+    'StudioV2Execution',
+    'StudioV2ExecutionContext',
+    'StudioV2ExecutionStep',
+    'StudioV2Flow',
+    'StudioV2FlowRevision',
+    'StudioV2FlowValidate',
+  ],
+  TaskRouter: [
+    'TaskrouterV1Activity',
+    'TaskrouterV1Event',
+    'TaskrouterV1Task',
+    'TaskrouterV1TaskChannel',
+    'TaskrouterV1TaskQueue',
+    'TaskrouterV1TaskReservation',
+    'TaskrouterV1Worker',
+    'TaskrouterV1WorkerChannel',
+    'TaskrouterV1WorkerReservation',
+    'TaskrouterV1Workflow',
+    'TaskrouterV1Workspace',
+    'TaskrouterV1WorkspaceStatistics',
+  ],
+  Serverless: [
+    'ServerlessV1Asset',
+    'ServerlessV1AssetVersion',
+    'ServerlessV1Build',
+    'ServerlessV1Deployment',
+    'ServerlessV1Environment',
+    'ServerlessV1Function',
+    'ServerlessV1Service',
+    'ServerlessV1Variable',
+  ],
+  Account: ['Api20100401Account'],
+  PhoneNumbers: ['Api20100401IncomingPhoneNumber', 'Api20100401Address'],
+  Applications: ['Api20100401Application'],
+  Auth: ['Api20100401Token'],
+  AddOns: ['Api20100401AddOnResult'],
+  Usage: ['Api20100401Usage'],
+};
+
+const validateContext = (context, callback) => {
+  if (!context.ACCOUNT_SID || !context.API_KEY || !context.API_SECRET) {
+    const response = new Twilio.Response();
+    response.setStatusCode(400);
+    response.setBody({
+      error:
+        'required context variables ACCOUNT_SID or API_KEY or API_SECRET not found',
+    });
+
+    callback(null, response);
+
+    return false;
+  }
+
+  return true;
+};
+
+const getTags = (event) => {
+  if (!event.services) {
+    return defaultMessaging;
+  }
+
+  const services =
+    typeof event.services === 'string' ? [event.services] : event.services;
+  // MCP does not like additoinal keys
+  delete event.services;
+
+  const tags = [];
+  services.forEach((service) => {
+    if (TWILIO_TAG_MAP[service]) {
+      tags.push(...TWILIO_TAG_MAP[service]);
+    }
+  });
+
+  if (tags.length === 0) {
+    return ['Api20100401Message'];
+  }
+
+  return tags;
+};
+
+exports.handler = async function (context, event, callback) {
+  const id = randomUUID().substring(0, 6);
+  console.log(`[${id}]`, 'STARTED MCP called with method', event.method);
+  if (event.method === 'tools/call') {
+    console.log(
+      `[${id}]`,
+      'Calling tool',
+      event.params.name,
+      'with arguments',
+      event.params.arguments
+    );
+  }
+
+  if (!validateContext(context, callback)) {
+    return;
+  }
+
+  try {
+    const tags = getTags(event);
+    const { transport } = await createServer(context, event, tags);
+    const req = createReq(event);
+    const res = createRes(callback);
+
+    await transport.handleRequest(req, res);
+  } catch (error) {
+    console.log(`[${id}]`, 'FAILED MCP request with method', event.method);
+    console.log(error);
+
+    const response = new Twilio.Response();
+    response.setStatusCode(500);
+    response.setBody({ error: error.message });
+    callback(null, response);
+  } finally {
+    console.log(`[${id}]`, 'COMPLETED MCP request with method', event.method);
+  }
+};