updated readme's

.gitignore

@@ -143,3 +143,5 @@ twilio-oai
 .local/
 
 .DS_Store
+
+.vscode/

README.md

@@ -2,7 +2,97 @@
 
 This is a monorepo for the Model Context Protocol server that exposes all of Twilio APIs.
 
+## What is MCP?
+
+The Model Context Protocol (MCP) is a protocol for exchanging model context information between AI tools and services. This implementation allows you to expose Twilio's APIs to AI assistants and other tools that support the MCP protocol.
+
+## Prerequisites
+
+- Node.js 18 or higher
+- npm 9 or higher
+- A Twilio account with API credentials
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/twilio/mcp.git
+cd mcp
+
+# Install dependencies
+npm install
+
+# Build the packages
+npm run build
+```
+
 ## Packages
 
+This monorepo contains two main packages:
+
 - [mcp](/packages/mcp) - MCP Server for all of Twilio's Public API
-- [openapi-mcp-server](/packages/openapi-mcp-server) - An MCP server that serves the given OpenAPI spec.
+- [openapi-mcp-server](/packages/openapi-mcp-server) - An MCP server that serves the given OpenAPI spec
+
+Each package has its own comprehensive README with detailed documentation:
+
+- [MCP Package Documentation](/packages/mcp/README.md)
+- [OpenAPI MCP Server Documentation](/packages/openapi-mcp-server/README.md)
+
+## Quick Start
+
+The easiest way to get started is by using npx:
+
+```json
+{
+  "mcpServers": {
+    "twilio": {
+      "command": "npx",
+      "args": [
+        "-y", 
+        "@twilio-alpha/mcp",
+        "YOUR_ACCOUNT_SID/YOUR_API_KEY:YOUR_API_SECRET"
+      ]
+    }
+  }
+}
+```
+
+Visit [Twilio API Keys docs](https://www.twilio.com/docs/iam/api-keys) for information on how to find/create your API Key and Secret.
+
+## Basic Configuration Options
+
+Both packages accept configuration parameters. Here's a brief overview:
+
+- **MCP Server**: Use `--services` and `--tags` to filter which APIs to expose
+- **OpenAPI MCP Server**: Use `--apiPath` to specify OpenAPI spec files location
+
+For complete configuration details, refer to the package-specific documentation linked above.
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Run linting
+npm run lint
+
+# Fix linting issues
+npm run lint:fix
+```
+
+## Troubleshooting Common Issues
+
+- **Context Size Limitations**: Due to LLM context limits, load specific APIs using `--services` or `--tags`
+- **Authentication Issues**: Verify your Twilio API credentials format and permissions
+- **API Versioning**: Check you're using the correct API version (v1, v2, v3) for your needs
+
+For detailed troubleshooting guidance, see the package-specific documentation.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the ISC License - see the LICENSE file for details.

packages/mcp/README.md

@@ -97,4 +97,114 @@ If you prefer to play around with the server, you can clone the repository and r
     }
   }
 }
-```
+```
+
+## Available Services
+
+The following services can be used with the `--services` parameter:
+
+- `twilio_accounts_v1` - Account Management API
+- `twilio_api_v2010` - Core Twilio API
+- `twilio_assistants_v1` - Autopilot API
+- `twilio_bulkexports_v1` - Bulk Exports API
+- `twilio_chat_v1`, `twilio_chat_v2`, `twilio_chat_v3` - Chat API
+- `twilio_content_v1`, `twilio_content_v2` - Content API
+- `twilio_conversations_v1` - Conversations API
+- `twilio_events_v1` - Events API
+- `twilio_flex_v1`, `twilio_flex_v2` - Flex API
+- `twilio_frontline_v1` - Frontline API
+- `twilio_iam_v1` - Identity and Access Management API
+- `twilio_insights_v1` - Insights API
+- `twilio_intelligence_v2` - Intelligence API
+- `twilio_ip_messaging_v1`, `twilio_ip_messaging_v2` - IP Messaging API
+- `twilio_lookups_v1`, `twilio_lookups_v2` - Lookups API
+- `twilio_marketplace_v1` - Marketplace API
+- `twilio_messaging_v1` - Messaging API
+- `twilio_microvisor_v1` - Microvisor API
+- `twilio_monitor_v1`, `twilio_monitor_v2` - Monitor API
+- `twilio_notify_v1` - Notify API
+- `twilio_numbers_v1`, `twilio_numbers_v2` - Phone Numbers API
+- `twilio_oauth_v1` - OAuth API
+- `twilio_pricing_v1`, `twilio_pricing_v2` - Pricing API
+- `twilio_proxy_v1` - Proxy API
+- `twilio_routes_v2` - Routes API
+- `twilio_serverless_v1` - Serverless API
+- `twilio_studio_v1`, `twilio_studio_v2` - Studio API
+- `twilio_supersim_v1` - Super SIM API
+- `twilio_sync_v1` - Sync API
+- `twilio_taskrouter_v1` - TaskRouter API
+- `twilio_trunking_v1` - Trunking API
+- `twilio_trusthub_v1` - Trust Hub API
+- `twilio_verify_v2` - Verify API
+- `twilio_video_v1` - Video API
+- `twilio_voice_v1` - Voice API
+- `twilio_wireless_v1` - Wireless API
+
+For example, to use the Chat API v3, you would specify `--services twilio_chat_v3` in your configuration.
+
+## Available Tags
+
+The following tags can be used with the `--tags` parameter to select specific API endpoints:
+
+### Accounts API Tags
+- `AccountsV1AuthTokenPromotion` - Auth Token Promotion
+- `AccountsV1Aws` - AWS Integration
+- `AccountsV1BulkConsents` - Bulk Consents Management
+- `AccountsV1BulkContacts` - Bulk Contacts Management
+- `AccountsV1PublicKey` - Public Key Management
+- `AccountsV1Safelist` - Safelist Management
+- `AccountsV1SecondaryAuthToken` - Secondary Auth Token Management
+
+### API 2010 Tags (Core Twilio API)
+- `Api20100401Account` - Account Management
+- `Api20100401AddOnResult` - AddOn Results
+- `Api20100401Address` - Address Management
+- `Api20100401Application` - Application Management
+- `Api20100401Call` - Call Management
+- `Api20100401Conference` - Conference Management
+- `Api20100401IncomingPhoneNumber` - Incoming Phone Number Management
+- `Api20100401Message` - Message Management
+- `Api20100401Recording` - Recording Management
+- `Api20100401Token` - Token Management
+- `Api20100401Transcription` - Transcription Management
+- `Api20100401Usage` - Usage Management
+
+### Studio API Tags
+- `StudioV2Execution` - Flow Execution Management
+- `StudioV2ExecutionContext` - Flow Execution Context
+- `StudioV2ExecutionStep` - Flow Execution Steps
+- `StudioV2Flow` - Flow Management
+- `StudioV2FlowRevision` - Flow Revision Management
+
+### Conversations API Tags
+- `ConversationsV1Conversation` - Conversation Management
+- `ConversationsV1Message` - Message Management
+- `ConversationsV1Participant` - Participant Management
+- `ConversationsV1Service` - Service Management
+- `ConversationsV1User` - User Management
+
+### Serverless API Tags
+- `ServerlessV1Asset` - Asset Management
+- `ServerlessV1AssetVersion` - Asset Version Management
+- `ServerlessV1Build` - Build Management
+- `ServerlessV1Deployment` - Deployment Management
+- `ServerlessV1Environment` - Environment Management
+- `ServerlessV1Function` - Function Management
+- `ServerlessV1Service` - Service Management
+- `ServerlessV1Variable` - Environment Variable Management
+
+### TaskRouter API Tags
+- `TaskrouterV1Activity` - Activity Management
+- `TaskrouterV1Event` - Event Management
+- `TaskrouterV1Task` - Task Management
+- `TaskrouterV1TaskChannel` - Task Channel Management
+- `TaskrouterV1TaskQueue` - Task Queue Management
+- `TaskrouterV1TaskReservation` - Task Reservation Management
+- `TaskrouterV1Worker` - Worker Management
+- `TaskrouterV1WorkerChannel` - Worker Channel Management
+- `TaskrouterV1WorkerReservation` - Worker Reservation Management
+- `TaskrouterV1Workflow` - Workflow Management
+- `TaskrouterV1Workspace` - Workspace Management
+- `TaskrouterV1WorkspaceStatistics` - Workspace Statistics
+
+This list includes the most commonly used tags. Each service has its own set of tags that follow the pattern `{ServiceName}{Version}{Resource}`. You can combine multiple tags by separating them with commas in your configuration.