Updating helper files around mcp-server template

Author: bpartridge83

mcp-server/README.md

@@ -1,23 +1,17 @@
 # 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
+Functions to run an MCP server for Twilio API tools
 
 ## Create a new project with the template
 
 1. Install the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart#install-twilio-cli)
+
+Recommended method, homebrew: 
+```shell
+brew tap twilio/brew && brew install twilio
+twilio login
+```
+
 2. Install the [serverless toolkit](https://www.twilio.com/docs/labs/serverless-toolkit/getting-started)
 
 ```shell
@@ -26,37 +20,142 @@ twilio plugins:install @twilio-labs/plugin-serverless
 
 3. Initiate a new project
 
-```
+```shell
 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):
+4. Set environment variables
 
-```
+This MCP server uses API keys to authenticate the Twilio API requests. A file named `.env` is used to store the values for those environment variables.
+
+In your `.env` file, set the following values:
+
+* API_KEY
+* API_SECRET
+
+ℹ️ You can generate a new API key in the [Twilio Console](https://www.twilio.com/console/project/api-keys)
+
+5. Start the server with the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart):
+
+```shell
 twilio serverless:start
 ```
 
 ℹ️ Check the developer console and terminal for any errors, make sure you've set your environment variables.
 
+6. Test your local MCP server using the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
+
+```shell
+npx @modelcontextprotocol/inspector
+```
+
+For local testing, use the following configuration:
+
+* **Transport Type**: Streamable HTTP
+* **URL**: http://localhost:{port}/mcp
+
+ℹ️ When testing the protected /mcp endpoint locally, no authentication header is required.
+
 ## 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)
+Deploy your functions with the following command. Note: you must run this command 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):
 
-```
+```shell
 twilio serverless:deploy
 ```
 
+### Testing your MCP server
+
+🐛 We're aware of a reported issue with the MCP Inspector project and the authentication header. You'll need to use your MCP client to connect to your deployed MCP server.
+
 ## Integration with MCP clients
 
-`https://<functions-domain>.twil.io/mcp?services=`
+* **URL**: `https://{functions-domain}.twil.io/mcp?services=`
+* **Authentication Header**: 
+  * Key: `x-twilio-signature`
+  * Value: {Valid Twilio signature}
+
+### Code samples for generating a Twilio signature
+
+Learn more about the use of `x-twilio-signature` header for executing `protected` Functions. https://www.twilio.com/docs/serverless/functions-assets/visibility#protected 
+
+The sample code below assuming that the following environment variables are set:
+* TWILIO_AUTH_TOKEN
+* TWILIO_BASE_DOMAIN
+
+#### JavaScript
+
+```javascript
+const crypto = require("crypto");
+const dotenv = require("dotenv");
+
+dotenv.config();
+
+function getSignature(authToken, url, params) {
+  var data = Object.keys(params)
+    .sort()
+    .reduce((acc, key) => acc + key + params[key], url);
+
+  return (
+    crypto
+      .createHmac("sha1", authToken)
+      .update(Buffer.from(data, "utf-8"))
+      .digest("base64")
+  );
+}
+
+const signature =
+  twilio.getExpectedTwilioSignature(
+    process.env.TWILIO_AUTH_TOKEN,
+    `${process.env.TWILIO_DOMAIN_NAME}/mcp`,
+    {}
+  );
+```
+
+Or, with the `twilio` Node package installed:
+
+```javascript
+const twilio = require("twilio");
+const dotenv = require("dotenv");
+
+dotenv.config();
+
+const signature =
+  twilio.getExpectedTwilioSignature(
+    process.env.TWILIO_AUTH_TOKEN,
+    `${process.env.TWILIO_DOMAIN_NAME}/mcp`,
+    {}
+  );
+```
+
+#### Python
+
+```python
+import os
+from dotenv import load_dotenv
+from twilio.request_validator import RequestValidator
+
+auth_token = os.environ.get("TWILIO_AUTH_TOKEN")
+base_domain = os.environ.get("TWILIO_DOMAIN_NAME")
+
+url = f"{base_domain}/mcp?services=Messaging"
+validator = RequestValidator(auth_token)
+signature = validator.compute_signature(url, {})
+```
+
+### Services
+
+Use the querystring parameter `?services=` to specify a set of tools based on the needs of your MCP client. Set multiple services by passing multiple `services` key/value pairs.
+
+**Examples:**
 
-Header: x-twilio-signature
+* `/mcp?services=Voice`
+* `/mcp?services=Messaging&services=PhoneNumbers`
 
-@TODO: Code samples to generate x-twilio-signature
+**Available services:**
 
-Available services
 * Messaging (default)
 * Voice
 * VoiceAddOns
@@ -77,8 +176,8 @@ Available services
 
 ## 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:
+This 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.
+- Always set your MCP client to require tool approval 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.

mcp-server/assets/index.html

@@ -39,7 +39,7 @@ <h1>
                     <img src="https://twilio-labs.github.io/function-templates/static/v1/success.svg" />
                     <div>
                         <p>Welcome!</p>
-                        <p>Your remote MCP server!</p>
+                        <p>Your MCP server!</p>
                     </div>
                 </h1>
                 <section>

templates.json

@@ -353,7 +353,7 @@
     {
       "id": "mcp-server",
       "name": "MCP Server",
-      "description": "Functions to run a remote MCP server for Twilio API tools"
+      "description": "Functions to run an MCP server for Twilio API tools"
     }
   ]
 }