diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 97593e8b5..513a8f334 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -71,6 +71,12 @@ "description": "Tools and techniques for maximizing GitHub Copilot effectiveness through better context management. Includes guidelines for structuring code, an agent for planning multi-file changes, and prompts for context-aware development.", "version": "1.0.0" }, + { + "name": "context-matic", + "source": "context-matic", + "description": "General-purpose AI models are trained on public code and documentation, much of it outdated. They have no awareness of an actual API version, latest SDKs, or recommended workflows. ContextMatic gives GitHub Copilot deterministic, version-aware API context generated directly from API definitions and SDKs. Instead of guessing from public examples, the agent is grounded in current SDK versions, idiomatic code samples, and recommended integration workflows.", + "version": "0.1.0" + }, { "name": "copilot-sdk", "source": "copilot-sdk", diff --git a/docs/README.plugins.md b/docs/README.plugins.md index 08f908163..3b491884b 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -31,6 +31,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | [cast-imaging](../plugins/cast-imaging/README.md) | A comprehensive collection of specialized agents for software analysis, impact assessment, structural quality advisories, and architectural review using CAST Imaging. | 3 items | cast-imaging, software-analysis, architecture, quality, impact-analysis, devops | | [clojure-interactive-programming](../plugins/clojure-interactive-programming/README.md) | Tools for REPL-first Clojure workflows featuring Clojure instructions, the interactive programming chat mode and supporting guidance. | 2 items | clojure, repl, interactive-programming | | [context-engineering](../plugins/context-engineering/README.md) | Tools and techniques for maximizing GitHub Copilot effectiveness through better context management. Includes guidelines for structuring code, an agent for planning multi-file changes, and prompts for context-aware development. | 4 items | context, productivity, refactoring, best-practices, architecture | +| [context-matic](../plugins/context-matic/README.md) | General-purpose AI models are trained on public code and documentation, much of it outdated. They have no awareness of an actual API version, latest SDKs, or recommended workflows. ContextMatic gives GitHub Copilot deterministic, version-aware API context generated directly from API definitions and SDKs. Instead of guessing from public examples, the agent is grounded in current SDK versions, idiomatic code samples, and recommended integration workflows. | 2 items | api-context, api-integration, mcp, sdk, apimatic, third-party-apis, sdks | | [copilot-sdk](../plugins/copilot-sdk/README.md) | Build applications with the GitHub Copilot SDK across multiple programming languages. Includes comprehensive instructions for C#, Go, Node.js/TypeScript, and Python to help you create AI-powered applications. | 1 items | copilot-sdk, sdk, csharp, go, nodejs, typescript, python, ai, github-copilot | | [csharp-dotnet-development](../plugins/csharp-dotnet-development/README.md) | Essential prompts, instructions, and chat modes for C# and .NET development including testing, documentation, and best practices. | 9 items | csharp, dotnet, aspnet, testing | | [csharp-mcp-development](../plugins/csharp-mcp-development/README.md) | Complete toolkit for building Model Context Protocol (MCP) servers in C# using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 2 items | csharp, mcp, model-context-protocol, dotnet, server-development | diff --git a/docs/README.skills.md b/docs/README.skills.md index c6cfc3229..5ae8e8ed5 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -156,6 +156,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [gtm-technical-product-pricing](../skills/gtm-technical-product-pricing/SKILL.md) | Pricing strategy for technical products. Use when choosing usage-based vs seat-based, designing freemium thresholds, structuring enterprise pricing conversations, deciding when to raise prices, or using price as a positioning signal. | None | | [image-manipulation-image-magick](../skills/image-manipulation-image-magick/SKILL.md) | Process and manipulate images using ImageMagick. Supports resizing, format conversion, batch processing, and retrieving image metadata. Use when working with images, creating thumbnails, resizing wallpapers, or performing batch image operations. | None | | [import-infrastructure-as-code](../skills/import-infrastructure-as-code/SKILL.md) | Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type. | None | +| [integrate-context-matic](../skills/integrate-context-matic/SKILL.md) | Discovers and integrates third-party APIs using the context-matic MCP server. Uses `fetch_api` to find available API SDKs, `ask` for integration guidance, `model_search` and `endpoint_search` for SDK details. Use when the user asks to integrate a third-party API, add an API client, implement features with an external API, or work with any third-party API or SDK. | None | | [issue-fields-migration](../skills/issue-fields-migration/SKILL.md) | Bulk-migrate metadata to GitHub issue fields from two sources: repo labels (e.g. priority labels to a Priority field) and Project V2 fields. Use when users say "migrate my labels to issue fields", "migrate project fields to issue fields", "convert labels to issue fields", "copy project field values to issue fields", or ask about adopting issue fields. Issue fields are org-level typed metadata (single select, text, number, date) that replace label-based workarounds with structured, searchable, cross-repo fields. | `references/issue-fields-api.md`
`references/labels-api.md`
`references/projects-api.md` | | [java-add-graalvm-native-image-support](../skills/java-add-graalvm-native-image-support/SKILL.md) | GraalVM Native Image expert that adds native image support to Java applications, builds the project, analyzes build errors, applies fixes, and iterates until successful compilation using Oracle best practices. | None | | [java-docs](../skills/java-docs/SKILL.md) | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. | None | @@ -195,6 +196,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [next-intl-add-language](../skills/next-intl-add-language/SKILL.md) | Add new language to a Next.js + next-intl application | None | | [noob-mode](../skills/noob-mode/SKILL.md) | Plain-English translation layer for non-technical Copilot CLI users. Translates every approval prompt, error message, and technical output into clear, jargon-free English with color-coded risk indicators. | `references/examples.md`
`references/glossary.md` | | [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None | +| [onboard-context-matic](../skills/onboard-context-matic/SKILL.md) | Interactive onboarding tour for the context-matic MCP server. Walks the user through what the server does, shows all available APIs, lets them pick one to explore, explains it in their project language, demonstrates model_search and endpoint_search live, and ends with a menu of things the user can ask the agent to do. USE FOR: first-time setup; "what can this MCP do?"; "show me the available APIs"; "onboard me"; "how do I use the context-matic server"; "give me a tour". DO NOT USE FOR: actually integrating an API end-to-end (use integrate-context-matic instead). | None | | [oo-component-documentation](../skills/oo-component-documentation/SKILL.md) | Create or update standardized object-oriented component documentation using a shared template plus mode-specific guidance for new and existing docs. | `assets/documentation-template.md`
`references/create-mode.md`
`references/update-mode.md` | | [openapi-to-application-code](../skills/openapi-to-application-code/SKILL.md) | Generate a complete, production-ready application from an OpenAPI specification | None | | [pdftk-server](../skills/pdftk-server/SKILL.md) | Skill for using the command-line tool pdftk (PDFtk Server) for working with PDF files. Use when asked to merge PDFs, split PDFs, rotate pages, encrypt or decrypt PDFs, fill PDF forms, apply watermarks, stamp overlays, extract metadata, burst documents into pages, repair corrupted PDFs, attach or extract files, or perform any PDF manipulation from the command line. | `references/download.md`
`references/pdftk-cli-examples.md`
`references/pdftk-man-page.md`
`references/pdftk-server-license.md`
`references/third-party-materials.md` | diff --git a/plugins/context-matic/.github/plugin/plugin.json b/plugins/context-matic/.github/plugin/plugin.json new file mode 100644 index 000000000..dbccd3949 --- /dev/null +++ b/plugins/context-matic/.github/plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "context-matic", + "description": "General-purpose AI models are trained on public code and documentation, much of it outdated. They have no awareness of an actual API version, latest SDKs, or recommended workflows. ContextMatic gives GitHub Copilot deterministic, version-aware API context generated directly from API definitions and SDKs. Instead of guessing from public examples, the agent is grounded in current SDK versions, idiomatic code samples, and recommended integration workflows.", + "version": "0.1.0", + "keywords": [ + "api-context", + "api-integration", + "mcp", + "sdk", + "apimatic", + "third-party-apis", + "sdks" + ], + "author": { + "name": "APIMatic", + "email": "developer@apimatic.io" + }, + "homepage": "https://www.apimatic.io", + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "skills": [ + "./skills/integrate-context-matic/", + "./skills/onboard-context-matic/" + ] +} diff --git a/plugins/context-matic/.mcp.json b/plugins/context-matic/.mcp.json new file mode 100644 index 000000000..45542e51f --- /dev/null +++ b/plugins/context-matic/.mcp.json @@ -0,0 +1,10 @@ +{ + "mcpServers": { + "context-matic": { + "url": "https://chatbotapi.apimatic.io/mcp/plugins", + "headers": { + "X-Apimatic-Mcp-Client": "VsCode" + } + } + } +} diff --git a/plugins/context-matic/README.md b/plugins/context-matic/README.md new file mode 100644 index 000000000..b468be6f8 --- /dev/null +++ b/plugins/context-matic/README.md @@ -0,0 +1,463 @@ +# ContextMatic Plugin + +Coding agents hallucinate APIs. APIMatic Context gives them curated, versioned API and SDK docs. + +When a developer asks their agent to "integrate the payments API," it normally guesses, pulling from outdated training data or generic patterns that don't match the actual SDK. ContextMatic solves this by giving the agent authoritative, version-aware, SDK-native context at the exact moment it's needed. + +## Installation + +```bash +copilot plugin install context-matic@awesome-copilot +``` + +## What It Includes + +### MCP Server + +| Server | Description | +|--------|-------------| +| `context-matic` | Hosted MCP server for version-aware third-party API integration and SDK discovery. | + +### Skills + +| Skill | Description | +|-------|-------------| +| `/integrate-context-matic` | Focused workflow for integrating supported third-party APIs using authoritative SDK and endpoint information. | +| `/onboard-context-matic` | Guided walkthrough of the ContextMatic MCP server, supported APIs, and tool usage. | + +## What ContextMatic Does + +ContextMatic gives GitHub Copilot version-aware API and SDK guidance grounded in real API definitions and SDKs instead of generic public examples. It helps with: + +- API discovery by project language +- Authentication and quickstart guidance +- Endpoint lookup with parameter and response details +- Model lookup with typed property definitions +## Supported APIs + +The plugin gives the agent SDK-native context for the following APIs, available in TypeScript, C#, Python, Java, PHP, and Ruby: + +| API | Description | +|-----|-------------| +| **Adyen API** | Payment processing: retrieve payment methods, create orders, manage stored payment tokens | +| **Google Maps APIs** | Location services: geocoding, directions, distance matrix, elevation, roads, and places | +| **PayPal Server SDK** | Payment flows: orders, payments, vault, transaction search, and subscriptions | +| **PayQuicker API** | Payment and financial services: program agreements, bank accounts, spendback quotes | +| **Slack API** | Workspace automation: OAuth bots, messaging, conversation management | +| **Spotify Web API** | Music and podcasts: library management, playback control, discovery | +| **Tesla Fleet Management API** | Vehicle and fleet operations: charging history, vehicle commands, energy management | +| **Tesser API Portal** | Digital payments: payment intents, onchain payments, app management | +| **Twilio API** | Communications: SMS, voice, video, and verification services | + +This list is growing. [Suggest a new API](#contributing) to request support for one not listed here. + +--- + +## What the Plugin Gives the Agent + +Once installed, the plugin exposes seven tools to the agent. Each tool is mapped to a specific stage of the integration workflow: + +| Tool | Developer task it enables | +|------|--------------------------| +| `fetch_api` | Lists all available APIs with their name, key, and description. The agent calls this first to discover which APIs are available for your project's language. | +| `ask` | Chat with API Copilot for step-by-step integration guidance and general API questions: authentication setup, client initialization, feature behavior, framework-specific patterns (e.g. "How do I initialize the Twilio client in Laravel?"), and idiomatic SDK code samples. | +| `endpoint_search` | Returns an SDK endpoint method's description, input parameters, and response shape by method name. | +| `model_search` | Returns an SDK model's full definition and its typed properties by name. Call this before writing code that constructs request bodies or reads response objects. | +| `update_activity` | Records concrete integration milestones such as SDK setup, auth configuration, the first successful API call, and resolved errors. The agent calls this after a milestone has actually been reached in code or infrastructure. | +| `add_guidelines` | Adds language-specific guideline files such as security, testing, or workflow guidance that the agent can follow during implementation. | +| `add_skills` | Adds reusable project skills such as `{language}-conventions` so future API integration work can follow the project's language-specific conventions. | + +For step-by-step guidance on using these tools together, invoke the `/integrate-context-matic` skill in your agent. It tells the agent when and how to call each tool throughout your integration workflow. + +--- + +## From Prompt to Code: How the Tools Work Together + +The seven tools are designed to chain together in a natural integration workflow. Here is a concrete example of what happens under the hood when the agent receives a real task: + +**Your prompt:** _"/integrate-context-matic Add Twilio SMS notifications to my Next.js app. Send a text when an order ships."_ + +| Step | Tool called | What it returns | +|------|-------------|----------------| +| 1 | `add_guidelines` (`language=typescript`) | Adds project guideline files the agent can follow for security, testing, and implementation workflow before starting the API integration. | +| 2 | `add_skills` (`language=typescript`) | Adds reusable language-specific skills such as conventions guidance so the project setup matches future integration work. | +| 3 | `fetch_api` (`language=typescript`) | Discovers Twilio is available; returns its `key` | +| 4 | `ask` (`key=twilio`, query=_"How do I initialize the Twilio TypeScript client?"_) | Returns exact SDK setup code with auth configuration | +| 5 | `update_activity` (`milestone=auth_configured`) | After the returned SDK/auth configuration has been added to the app, records that credentials are wired into the app and the integration is ready for the first live call | +| 6 | `endpoint_search` (`query=createMessage`) | Returns the method signature, required parameters, and auth requirements for the SMS send endpoint | +| 7 | `model_search` (`query=CreateMessageRequest`) | Returns the full typed request model with every available field | +| 8 | `ask` (`query="How do I handle delivery status callbacks in Next.js?"`) | Returns webhook handling code aligned to the Twilio SDK | + +Each step completes in a single tool call. The agent handles the orchestration. You describe the goal, and it picks the right tool at the right time. + + +## MCP Server + +This plugin uses the ContextMatic MCP endpoint: + +```text +https://chatbotapi.apimatic.io/mcp/plugins +``` + +The plugin registers the MCP server through its plugin-root `.mcp.json` file so the server is available alongside the bundled skills. + +--- + +## Build a Full App in Minutes + +
+PayPal Instant Storefront — Node.js/Express · 30 min + +![PayPal](https://img.shields.io/badge/-PayPal-003087?logo=paypal&logoColor=white&labelColor=003087) ![Node.js](https://img.shields.io/badge/-Node.js-339933?logo=nodedotjs&logoColor=white&labelColor=339933) ![Express](https://img.shields.io/badge/-Express-000000?logo=express&logoColor=white&labelColor=000000) ![JavaScript](https://img.shields.io/badge/-JavaScript-F7DF1E?logo=javascript&logoColor=black&labelColor=F7DF1E) + +![paypalsampleapp](https://github.com/user-attachments/assets/dc3e5b02-934e-44b5-9df9-20387557babe) + +**What was built:** A full Node.js/Express storefront with product management, shareable checkout links per product, PayPal Smart Payment Buttons, server-side order creation and capture, and a payment history dashboard. + +**The prompt:** + +``` +/integrate-context-matic Build me a "PayPal Instant Storefront" app. +The app has a setup page where I enter my PayPal client-id and secret once, then +a product creation form where I enter a product name, description, price, currency, +and upload or provide product images. When I click "Generate Checkout Page" it +creates a live, shareable checkout URL like /checkout/abc123 that anyone can open — +they see the product details with images, price, description, and a working PayPal +Smart Payment Button. The payment flow should be fully server-side using the PayPal +Server SDK: backend creates the order when buyer clicks pay, captures it after +approval, and shows a confirmation page with order details. I should be able to +create multiple products and each gets its own unique checkout link I can share +with anyone. Include a simple dashboard where I can see all my products and their +checkout links, plus a list of completed payments showing order ID, buyer info, +amount, and status for each product. The checkout pages should be mobile-responsive +and look like real professional product pages. Support sandbox and live mode via +environment variables. Only use the Orders API and Payments API, do not use +Transaction Search or Vault. Make it deployable with npm install and npm start. +``` + +**How the tools were used:** + +| Step | Tool | Query | What it returned | +|------|------|-------|-----------------| +| 1 | `fetch_api` | `language=typescript` | Available APIs; identified PayPal Server SDK with key `paypal` | +| 2 | `ask` | SDK setup & environment switching | Client initialization code, `.env` structure, sandbox vs. live config via `Client.fromEnvironment` | +| 3 | `ask` | Order creation flow | End-to-end create → approve → capture flow with full TypeScript server-side code | +| 4 | `endpoint_search` | `ordersCreate` | `CreateOrder` method signature, `OrderRequest` body structure, response type `Order`, error codes | +| 5 | `endpoint_search` | `capture` | `CaptureOrder` contract — required `id` param, optional body, capture ID location in response | +| 6 | `model_search` | `OrderRequest` | Full request model properties; flagged `payer` and `application_context` as deprecated | +| 7 | `model_search` | `Money` | Currency code and value fields for structuring amounts | +| 8 | `ask` | Smart Payment Buttons | Frontend button integration — `createOrder` / `onApprove` wiring to backend endpoints | +| 9 | `endpoint_search` | `getOrder` | `GetOrder` method signature and response shape for the confirmation page | +| 10 | `model_search` | `PurchaseUnitRequest` | Full model with `amount`, `items`, `shipping`, and all optional fields | +| 11 | `model_search` | `Order` | Full response model — `status`, `purchaseUnits`, `links` (including the `approve` redirect URL) | + +**App outcome:** + +- One-time credential setup page with live sandbox validation +- Product creation with name, description, price, currency, and image upload +- Unique shareable checkout URL per product (`/checkout/abc123`) +- Server-side order creation and capture — no client secrets exposed +- Confirmation page with order ID, buyer info, and capture details +- Dashboard with all products, total revenue, and payment history +- Mobile-responsive checkout pages +- Deployable with `npm install && npm start` + +**Build time:** 10 min generation + 20 min testing = **30 minutes total** + +
+ +
+Spotify Music DNA Card — Python/Flask · 30 min + +![Spotify](https://img.shields.io/badge/-Spotify-1DB954?logo=spotify&logoColor=white&labelColor=1DB954) ![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white&labelColor=3776AB) ![Flask](https://img.shields.io/badge/-Flask-000000?logo=flask&logoColor=white&labelColor=000000) + +![spotifySampleApp](https://github.com/user-attachments/assets/63556c36-ba2d-417c-978c-5a4697e9b4e2) + +**What was built:** A Python/Flask web app where users authenticate via Spotify OAuth, fetch their top artists and tracks, retrieve audio features in batch, and analyze the data to produce a personalized "Music DNA" card — featuring a radar chart of average audio features, top 5 genres, most obscure artist, and a generated personality label — with a download/share button. Custom branding only; no Spotify logos. + +**The prompt:** + +``` +/integrate-context-matic Create a web app using Python where users log in with Spotify, +fetch their top artists and top tracks, then fetch audio features for those tracks. +Analyze the data to calculate average audio features, find the most obscure artist, +determine the top 5 genres, and generate a "music personality" label based on the +averages. Render all of this in a visually appealing DNA card with a radar chart, +top genres, most obscure artist, and personality label, and include a button to +download or share the card. Use your own branding and logo; do not include Spotify +logos anywhere. +``` + +**How the tools were used:** + +| Step | Tool | Query | What it returned | +|------|------|-------|-----------------| +| 1 | `fetch_api` | `language=python` | Available APIs; identified Spotify Web API SDK with key `spotify` | +| 2 | `ask` | SDK setup, OAuth 2.0 authorization code flow for user login | Full `pip install spotify-api-sdk` setup, `SpotifywebapiClient` initialization with `AuthorizationCodeAuthCredentials`, `.env` structure, `get_authorization_url()` → `fetch_token(code)` → `clone_with(o_auth_token=token)` flow, token refresh pattern | +| 3 | `ask` | How to fetch a user's top artists and top tracks | End-to-end code using `users_controller.get_users_top_artists()` and `users_controller.get_users_top_tracks()` with `time_range`, `limit`, `offset` params; reading `PagingArtistObject.items` and `PagingTrackObject.items` | +| 4 | `endpoint_search` | `get_users_top_artists` | Method signature — params `time_range`, `limit`, `offset`; response type `PagingArtistObject`; required scope `OAuthScopeEnum.USER_TOP_READ` | +| 5 | `endpoint_search` | `get_users_top_tracks` | Method signature — same params as top artists; response type `PagingTrackObject` with `List[TrackObject]` items | +| 6 | `endpoint_search` | `get_audio_features` | Single-track method via `tracks_controller.get_audio_features(id)`; response type `AudioFeaturesObject` | +| 7 | `endpoint_search` | `get_several_audio_features` | Batch method via `tracks_controller.get_several_audio_features(ids)` — takes comma-separated track IDs string; response type `ManyAudioFeatures` | +| 8 | `endpoint_search` | `get_current_users_profile` | `users_controller.get_current_users_profile()` — no params; response `PrivateUserObject`; required scopes `USER_READ_EMAIL`, `USER_READ_PRIVATE` | +| 9 | `model_search` | `AudioFeaturesObject` | All 14 properties — `danceability`, `energy`, `valence`, `acousticness`, `instrumentalness`, `liveness`, `speechiness`, `tempo`, `loudness`, `key`, `mode`, `time_signature`, `duration_ms`, `uri` (all 0.0–1.0 floats used for radar chart & personality logic) | +| 10 | `model_search` | `ArtistObject` | Properties `name`, `id`, `popularity` (0–100 int, used to find most obscure artist), `genres` (`List[str]`, used for top-5 genre aggregation), `images`, `external_urls` | +| 11 | `model_search` | `TrackObject` | Properties `id` (needed for audio features batch call), `name`, `popularity`, `artists` (`List[ArtistObject]`), `album`, `duration_ms`, `uri` | +| 12 | `model_search` | `PagingTrackObject` | Paging wrapper — `items` (`List[TrackObject]`), `total`, `next`, `offset`, `limit` | +| 13 | `model_search` | `ManyAudioFeatures` | Batch response wrapper — `audio_features` (`List[AudioFeaturesObject]`) for iterating and averaging | +| 14 | `model_search` | `PrivateUserObject` | User profile — `display_name`, `images` (`List[ImageObject]`), `id`, `email`, `country` (used to personalize the DNA card header) | + +**App outcome:** + +- Spotify OAuth 2.0 login via Authorization Code flow (no client secrets exposed to browser) +- Fetches current user's profile (`display_name`, avatar) to personalize the card +- Retrieves top 50 artists and top 50 tracks (configurable `time_range`: short/medium/long term) +- Batch-fetches audio features for all top tracks via `get_several_audio_features` +- Computes average audio features (danceability, energy, valence, acousticness, instrumentalness, liveness, speechiness) across all tracks +- Identifies the most obscure artist (lowest `popularity` score among top artists) +- Aggregates and ranks top 5 genres from all top artists' genre lists +- Generates a "music personality" label based on average feature thresholds (e.g., "Energetic Explorer", "Melancholic Dreamer", "Chill Acoustic Soul") +- Renders a visually appealing DNA card with: + - Radar chart (Chart.js) of the 7 average audio features + - Top 5 genres with visual badges + - Most obscure artist with name and popularity score + - Personality label prominently displayed + - User's display name and avatar +- Download card as PNG and share button (html2canvas) +- Custom branding and logo throughout — no Spotify logos anywhere +- Token refresh handling for long sessions +- Deployable with `pip install -r requirements.txt && python app.py` + +
+ +
+Google Maps Restaurant Roulette — PHP · 30 min + +![Google Maps](https://img.shields.io/badge/-Google%20Maps-4285F4?logo=googlemaps&logoColor=white&labelColor=4285F4) ![PHP](https://img.shields.io/badge/-PHP-777BB4?logo=php&logoColor=white&labelColor=777BB4) ![JavaScript](https://img.shields.io/badge/-JavaScript-F7DF1E?logo=javascript&logoColor=black&labelColor=F7DF1E) + +![google-maps-sample-app](https://github.com/user-attachments/assets/eafab114-ccf8-42f9-84c3-bc9706706118) + + +**What was built:** A PHP web app where users drop a pin (or use their location) on a Google Map, draw a travel-radius circle, and click "Spin" to randomly pick a restaurant within that radius. The app shows Google Places photos, a Street View storefront preview, and one-click directions — with a wheel animation and a "Spin Again" button for gamified suspense. Custom branding; credentials via `.env` file. + +**The prompt:** + +``` +/integrate-context-matic Create a web application using php and google maps platform +apis sdk. for credentials create an env file in which the user will provide the API +Key. The user will Drop a pin (or use your location) on the map, draw a circle for +how far you are willing to travel, and click "spin." The app picks a random restaurant +within that radius, shows you photos from Google Places, a Street View preview of the +storefront, and one-click directions. Not happy with the pick? Spin again. The wheel +animation and suspense make it feel like a game. +``` + +**How the tools were used:** + +| Step | Tool | Query | What it returned | +|------|------|-------|-----------------| +| 1 | `fetch_api` | `language=php` | Available APIs; identified Google Maps Platform SDK with key `googlemaps` (also: `paypal`, `spotify`, `maxio`, `verizon`) | +| 2 | `ask` | SDK setup, API key auth configuration | `composer require sdksio/google-maps-platform-sdk:1.0.3`, `GoogleMapsPlatformClientBuilder::init()` with `CustomQueryAuthenticationCredentialsBuilder::init('key')`, `.env` structure, `Environment::PRODUCTION` | +| 3 | `ask` | How to search for nearby restaurants within a radius | Full code using `$client->getPlacesApi()->nearbySearch($location, $radius, 'restaurant', ...)`, response handling via `isSuccess()` / `getResult()`, iterating `Place[]` results | +| 4 | `endpoint_search` | `nearbySearch` | Method signature — params `location` (`"lat,lng"`), `radius` (meters), `keyword`, `maxprice`, `minprice`, `opennow`, `pagetoken`, `rankby`, `type`, `language`; response type `PlacesNearbySearchResponse` | +| 5 | `endpoint_search` | `placeDetails` | Method signature — params `placeId`, `fields[]` (Basic/Contact/Atmosphere categories), `sessiontoken`, `language`, `region`; response type `PlacesDetailsResponse` | +| 6 | `endpoint_search` | `placePhoto` | Method signature — param `photoReference` (string), `maxheight`, `maxwidth` (1-1600px); response type `mixed` (raw image bytes) | +| 7 | `endpoint_search` | `streetView` | Method signature — params `size` (`"{w}x{h}"`, max 640px), `fov`, `heading`, `location`, `pitch`, `radius`, `source`; response type `mixed` (image bytes) | +| 8 | `endpoint_search` | `directions` | Method signature — params `destination`, `origin`, `mode`, `avoid`, `units`, `waypoints`, `language`, `region`; response type `DirectionsResponse` | +| 9 | `model_search` | `PlacesNearbySearchResponse` | Properties: `results` (`Place[]`), `status` (`PlacesSearchStatus`), `nextPageToken`, `errorMessage`, `htmlAttributions` | +| 10 | `model_search` | `PlacesDetailsResponse` | Properties: `result` (`Place`), `status` (`PlacesDetailsStatus`), `htmlAttributions`, `infoMessages` | +| 11 | `model_search` | `Place` | Full model — `name`, `placeId`, `formattedAddress`, `geometry` (`Geometry`), `rating`, `userRatingsTotal`, `priceLevel`, `photos` (`PlacePhoto[]`), `openingHours`, `types`, `vicinity`, `website`, `businessStatus`, `reviews` (`PlaceReview[]`) | +| 12 | `model_search` | `PlacePhoto` | Properties: `photoReference` (string, used for `placePhoto` call), `height`, `width`, `htmlAttributions` | +| 13 | `model_search` | `Geometry` | Properties: `location` (`LatLngLiteral`), `viewport` (`Bounds`) | +| 14 | `model_search` | `LatLngLiteral` | Properties: `lat` (float), `lng` (float) — used to extract coordinates for Street View and directions | +| 15 | `model_search` | `DirectionsResponse` | Properties: `routes` (`DirectionsRoute[]`), `status` (`DirectionsStatus`), `geocodedWaypoints`, `availableTravelModes`, `errorMessage` | +| 16 | `ask` | How to use Street View Static API for a given lat/lng | `$client->getStreetViewApi()->streetView($size, null, null, $location)`, returns raw image bytes; `streetViewMetadata()` for availability check | + +**App outcome:** + +- `.env` file with `GOOGLE_MAPS_API_KEY` for credentials +- Interactive Google Map with click-to-drop-pin or "Use My Location" (browser geolocation) +- Draggable circle overlay to set travel radius (meters) +- "Spin" button with wheel/slot-machine animation for suspense +- Backend `nearbySearch` with `keyword=restaurant` within the drawn radius +- Random restaurant selection from the `Place[]` results +- Place details card showing: + - Restaurant name, rating, price level, and formatted address + - Google Places photos carousel via `placePhoto` with `photoReference` + - Street View storefront preview via `streetView` using the place's lat/lng + - One-click directions link (Directions API or Google Maps URL with `origin` and `destination`) +- "Spin Again" button to re-roll without changing the pin/radius +- Pagination support via `nextPageToken` for more results +- Mobile-responsive map and card layout +- Deployable with `composer install && php -S localhost:8000` + +
+ +--- + +## Example Prompts to Try + +The best way to experience ContextMatic is to paste these prompts directly into Cursor or Claude Code after installing a plugin. Each prompt is written to naturally trigger the full tool chain. + +
+Quickstart: your first API call + +![Spotify](https://img.shields.io/badge/-Spotify-1DB954?logo=spotify&logoColor=white&labelColor=1DB954) ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white&labelColor=3178C6) +``` +/integrate-context-matic Set up the Spotify TypeScript SDK and fetch my top 5 tracks. +Show me the complete client initialization and the API call. +``` + +--- + +![Twilio](https://img.shields.io/badge/-Twilio-F22F46?logo=twilio&logoColor=white&labelColor=F22F46) ![PHP](https://img.shields.io/badge/-PHP-777BB4?logo=php&logoColor=white&labelColor=777BB4) +``` +/integrate-context-matic How do I authenticate with the Twilio API and send an SMS? +Give me the full PHP setup including the SDK client and the send call. +``` + +--- + +![Slack](https://img.shields.io/badge/-Slack-4A154B?logo=slack&logoColor=white&labelColor=4A154B) ![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white&labelColor=3776AB) +``` +/integrate-context-matic Walk me through initializing the Slack API client +in a Python script and posting a message to a channel. +``` + +
+ +
+Framework-specific integration + +![Google Maps](https://img.shields.io/badge/-Google%20Maps-4285F4?logo=googlemaps&logoColor=white&labelColor=4285F4) ![Next.js](https://img.shields.io/badge/-Next.js-000000?logo=nextdotjs&logoColor=white&labelColor=000000) ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white&labelColor=3178C6) +``` +/integrate-context-matic I'm building a Next.js app. Integrate the Google Maps +Places API to search for nearby restaurants and display them on a page. +Use the TypeScript SDK. +``` + +--- + +![Twilio](https://img.shields.io/badge/-Twilio-F22F46?logo=twilio&logoColor=white&labelColor=F22F46) ![Laravel](https://img.shields.io/badge/-Laravel-FF2D20?logo=laravel&logoColor=white&labelColor=FF2D20) ![PHP](https://img.shields.io/badge/-PHP-777BB4?logo=php&logoColor=white&labelColor=777BB4) +``` +/integrate-context-matic I'm using Laravel. Show me how to send a Twilio SMS +when a user registers. Include the PHP SDK setup, client initialization, and the +controller code. +``` + +--- + +![Twilio](https://img.shields.io/badge/-Twilio-F22F46?logo=twilio&logoColor=white&labelColor=F22F46) ![ASP.NET Core](https://img.shields.io/badge/-ASP.NET%20Core-512BD4?logo=dotnet&logoColor=white&labelColor=512BD4) ![C#](https://img.shields.io/badge/-C%23-239120?logo=csharp&logoColor=white&labelColor=239120) +``` +/integrate-context-matic I have an ASP.NET Core app. Add Twilio webhook handling +so I can receive delivery status callbacks when an SMS is sent. +``` + +
+ +
+Chaining tools for full integrations + +These prompts are designed to exercise the full plugin workflow; from API discovery through endpoint lookup to production-ready code. + +![Twilio](https://img.shields.io/badge/-Twilio-F22F46?logo=twilio&logoColor=white&labelColor=F22F46) ![Next.js](https://img.shields.io/badge/-Next.js-000000?logo=nextdotjs&logoColor=white&labelColor=000000) ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white&labelColor=3178C6) +``` +/integrate-context-matic I want to add real-time order shipping notifications +to my Next.js store. Use Twilio to send an SMS when the order status changes to +"shipped". Show me the full integration: SDK setup, the correct endpoint and its +parameters, and the TypeScript code. +``` + +--- + +![Slack](https://img.shields.io/badge/-Slack-4A154B?logo=slack&logoColor=white&labelColor=4A154B) ![Spotify](https://img.shields.io/badge/-Spotify-1DB954?logo=spotify&logoColor=white&labelColor=1DB954) ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white&labelColor=3178C6) +``` +/integrate-context-matic I need to post a Slack message every time a Spotify +track changes in my playlist monitoring app. Walk me through integrating both APIs +in TypeScript — start by discovering what's available, then show me the auth setup +and the exact API calls. +``` + +--- + +![Google Maps](https://img.shields.io/badge/-Google%20Maps-4285F4?logo=googlemaps&logoColor=white&labelColor=4285F4) ![ASP.NET Core](https://img.shields.io/badge/-ASP.NET%20Core-512BD4?logo=dotnet&logoColor=white&labelColor=512BD4) ![C#](https://img.shields.io/badge/-C%23-239120?logo=csharp&logoColor=white&labelColor=239120) +``` +/integrate-context-matic In my ASP.NET Core app, I want to geocode user +addresses using Google Maps and cache the results. Look up the geocode endpoint +and response model, then generate the C# code including error handling. +``` + +
+ +
+Debugging and error handling + +![Spotify](https://img.shields.io/badge/-Spotify-1DB954?logo=spotify&logoColor=white&labelColor=1DB954) ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white&labelColor=3178C6) +``` +/integrate-context-matic My Spotify API call is returning 401. What OAuth flow +should I be using and how does the TypeScript SDK handle token refresh automatically? +``` + +--- + +![Slack](https://img.shields.io/badge/-Slack-4A154B?logo=slack&logoColor=white&labelColor=4A154B) ![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white&labelColor=3776AB) +``` +/integrate-context-matic My Slack message posts are failing intermittently +with rate limit errors. How does the Python SDK expose rate limit information and +what's the recommended retry pattern? +``` + +
+ +--- + +## Typical Use Cases + +- Discover which supported APIs are available for a TypeScript, Python, Java, PHP, Ruby, Go, or C# project +- Get step-by-step integration guidance for a supported third-party API in the project's language +- Set up authentication, client initialization, and the first API call using version-aware SDK guidance +- Inspect request and response models before writing code that depends on SDK types +- Look up the exact methods, parameters, and response types needed during implementation + +## How APIMatic Generates context for an API + +![API integration using ContextMatic](https://github.com/apimatic/context-matic/blob/dev/assets/images/image.png?raw=true) + +APIMatic takes your OpenAPI specification through the same SDK generation pipeline it uses to produce idiomatic, type-safe SDKs in 10+ languages. The resulting MCP server exposes the SDK documentation and integration patterns as structured tool responses that AI assistants can consume natively. + +This means the context the AI receives is: +- Derived from actual generated SDK code, not raw documentation +- Inclusive of idiomatic patterns, typed models, and error handling +- Aligned to the current version of your API spec + +For API providers: [request a demo](https://www.apimatic.io/request-demo) to generate context for your API. + +## Source + +This plugin contribution is adapted from the APIMatic ContextMatic project and packaged for Awesome Copilot. + +GitHub source: + +- https://github.com/apimatic/context-matic + +## Contributing + +Have a request or found an issue? Use one of the templates below: + +- [Request a new language](https://github.com/apimatic/context-matic/issues/new?template=language-request.yml) — ask for support for a new SDK language (e.g., Swift, Kotlin, Rust) +- [Request a new API](https://github.com/apimatic/context-matic/issues/new?template=api-request.yml) — ask for a new third-party API to be added to the catalog +- [Report an issue or give feedback](https://github.com/apimatic/context-matic/issues/new?template=issue-feedback.yml) — report a bug, share feedback, or suggest an improvement to an existing tool + +For anything else, [open a blank issue](https://github.com/apimatic/context-matic/issues/new) or reach out at [support@apimatic.io](mailto:support@apimatic.io). + +## Learn More + +- [Product page](https://www.apimatic.io/product/context-plugins) +- [Blog: From API Portals to Cursor](https://www.apimatic.io/blog/from-api-portals-to-cursor) +- [Case Study](https://www.apimatic.io/product/context-plugins/case-study) + +--- + +## License + +MIT diff --git a/skills/integrate-context-matic/SKILL.md b/skills/integrate-context-matic/SKILL.md new file mode 100644 index 000000000..90251e267 --- /dev/null +++ b/skills/integrate-context-matic/SKILL.md @@ -0,0 +1,108 @@ +--- +name: integrate-context-matic +description: 'Discovers and integrates third-party APIs using the context-matic MCP server. Uses `fetch_api` to find available API SDKs, `ask` for integration guidance, `model_search` and `endpoint_search` for SDK details. Use when the user asks to integrate a third-party API, add an API client, implement features with an external API, or work with any third-party API or SDK.' +--- + +# API Integration + +When the user asks to integrate a third-party API or implement anything involving an external API or SDK, follow this workflow. Do not rely on your own knowledge for available APIs or their capabilities — always use the context-matic MCP server. + +## When to Apply + +Apply this skill when the user: +- Asks to integrate a third-party API +- Wants to add a client or SDK for an external service +- Requests implementation that depends on an external API +- Mentions a specific API (e.g. PayPal, Twilio) and implementation or integration + +## Workflow + +### 1. Ensure Guidelines and Skills Exist + +#### 1a. Detect the Project's Primary Language + +Before checking for guidelines or skills, identify the project's primary programming language by inspecting the workspace: + +| File / Pattern | Language | +|---|---| +| `*.csproj`, `*.sln` | `csharp` | +| `package.json` with `"typescript"` dep or `.ts` files | `typescript` | +| `requirements.txt`, `pyproject.toml`, `*.py` | `python` | +| `go.mod`, `*.go` | `go` | +| `pom.xml`, `build.gradle`, `*.java` | `java` | +| `Gemfile`, `*.rb` | `ruby` | +| `composer.json`, `*.php` | `php` | + +Use the detected language in all subsequent steps wherever `language` is required. + +#### 1b. Check for Existing Guidelines and Skills + +Check whether guidelines and skills have already been added for this project by looking for their presence in the workspace. + +- `{language}-conventions` is the skill produced by **add_skills**. +- `{language}-security-guidelines.md` and `{language}-test-guidelines.md` are language-specific guideline files produced by **add_guidelines**. +- `update-activity-workflow.md` is a workflow guideline file produced by **add_guidelines** (it is not language-specific). +- Check these independently. Do not treat the presence of one set as proof that the other set already exists. +- **If any required guideline files for this project are missing:** Call **add_guidelines**. +- **If `{language}-conventions` is missing for the project's language:** Call **add_skills**. +- **If all required guideline files and `{language}-conventions` already exist:** Skip this step and proceed to step 2. + +### 2. Discover Available APIs + +Call **fetch_api** to find available APIs — always start here. + +- Provide the `language` parameter using the language detected in step 1a. +- The response returns available APIs with their names, descriptions, and `key` values. +- Identify the API that matches the user's request based on the name and description. +- Extract the correct `key` for the user's requested API before proceeding. This key will be used for all subsequent tool calls related to that API. + +**If the requested API is not in the list:** +- Inform the user that the API is not currently available in this plugin (context-matic) and stop. +- Request guidance from user on how to proceed with the API's integration. + +### 3. Get Integration Guidance + +- Provide `ask` with: `language`, `key` (from step 2), and your `query`. +- Break complex questions into smaller focused queries for best results: + - _"How do I authenticate?"_ + - _"How do I create a payment?"_ + - _"What are the rate limits?"_ + +### 4. Look Up SDK Models and Endpoints (as needed) + +These tools return definitions only — they do not call APIs or generate code. + +- **model_search** — look up a model/object definition. + - Provide: `language`, `key`, and an exact or partial case-sensitive model name as `query` (e.g. `availableBalance`, `TransactionId`). +- **endpoint_search** — look up an endpoint method's details. + - Provide: `language`, `key`, and an exact or partial case-sensitive method name as `query` (e.g. `createUser`, `get_account_balance`). + +### 5. Record Milestones + +Call **update_activity** (with the appropriate `milestone`) whenever one of these is **concretely reached in code or infrastructure** — not merely mentioned or planned: + +| Milestone | When to pass it | +|---|---| +| `sdk_setup` | SDK package is installed in the project (e.g. `npm install`, `pip install`, `go get` has run and succeeded). | +| `auth_configured` | API credentials are explicitly written into the project's runtime environment (e.g. present in a `.env` file, secrets manager, or config file) **and** referenced in actual code. | +| `first_call_made` | First API call code written and executed | +| `error_encountered` | Developer reports a bug, error response, or failing call | +| `error_resolved` | Fix applied and API call confirmed working | + +## Checklist + +- [ ] Project's primary language detected (step 1a) +- [ ] `add_guidelines` called if guideline files were missing, otherwise skipped +- [ ] `add_skills` called if `{language}-conventions` was missing, otherwise skipped +- [ ] `fetch_api` called with correct `language` for the project +- [ ] Correct `key` identified for the requested API (or user informed if not found) +- [ ] `update_activity` called only when a milestone is concretely reached in code/infrastructure — never for questions, searches, or tool lookups +- [ ] `update_activity` called with the appropriate `milestone` at each integration milestone +- [ ] `ask` used for integration guidance and code samples +- [ ] `model_search` / `endpoint_search` used as needed for SDK details +- [ ] Project compiles after each code modification + +## Notes + +- **API not found**: If an API is missing from `fetch_api`, do not guess at SDK usage — inform the user that the API is not currently available in this plugin and stop. +- **update_activity and fetch_api**: `fetch_api` is API discovery, not integration — do not call `update_activity` before it. diff --git a/skills/onboard-context-matic/SKILL.md b/skills/onboard-context-matic/SKILL.md new file mode 100644 index 000000000..21e45c826 --- /dev/null +++ b/skills/onboard-context-matic/SKILL.md @@ -0,0 +1,293 @@ +--- +name: onboard-context-matic +description: 'Interactive onboarding tour for the context-matic MCP server. Walks the user through what the server does, shows all available APIs, lets them pick one to explore, explains it in their project language, demonstrates model_search and endpoint_search live, and ends with a menu of things the user can ask the agent to do. USE FOR: first-time setup; "what can this MCP do?"; "show me the available APIs"; "onboard me"; "how do I use the context-matic server"; "give me a tour". DO NOT USE FOR: actually integrating an API end-to-end (use integrate-context-matic instead).' +--- + +# Onboarding: ContextMatic MCP + +This skill delivers a guided, interactive tour of the `context-matic` MCP server. Follow every +phase in order. Stop after each interaction point and wait for the user's reply before continuing. + +> **Agent conduct rules — follow throughout the entire skill:** +> - **Never narrate the skill structure.** Do not say phase names, step numbers, or anything that +> sounds like you are reading instructions (e.g., "In Phase 1 I will…", "Step 1a:", "As per the +> skill…"). Deliver the tour as a natural conversation. +> - **Announce every tool call before making it.** One short sentence is enough — tell the user +> what you are about to look up and why, then call the tool. Example: *"Let me pull up the list +> of available APIs for your project language."* This keeps the user informed and prevents +> silent, unexplained pauses. + +--- + +## Phase 0 — Opening statement and tool walkthrough + +Begin with a brief, plain-language explanation of what the server does. Say it in your own words +based on the following facts: + +> The **context-matic** MCP server solves a fundamental problem with AI-assisted coding: general +> models are trained on public code that is often outdated, incorrect, or missing entirely for newer +> SDK versions. This server acts as a **live, version-aware grounding layer**. Instead of the agent +> guessing at SDK usage from training data, it queries the server for the *exact* SDK models, +> endpoints, auth patterns, and runnable code samples that match the current API version and the +> project's programming language. + +After explaining the problem the server solves, walk through each of the four tools as if +introducing them to someone using the server for the first time. For each tool, explain: +- **What it is** — give it a memorable one-line description +- **When you would use it** — a concrete, relatable scenario +- **What it gives back** — the kind of output the user will see + +Use the following facts as your source, but say it conversationally — do not present a raw table: + +> | Tool | What it does | When to use it | What you get back | +> |---|---|---|---| +> | `fetch_api` | Lists all APIs available on this server for a given language | "What APIs can I use?" / Starting a new project | A named list of available APIs with short descriptions | +> | `ask` | Answers integration questions with version-accurate guidance and code samples | "How do I authenticate?", "Show me the quickstart", "What's the right way to do X?" | Step-by-step guidance and runnable code samples grounded in the actual SDK version | +> | `model_search` | Looks up an SDK model/object definition and its typed properties | "What fields does an Order have?", "Is this property required?" | The model's name, description, and a full typed property list (required vs. optional, nested types) | +> | `endpoint_search` | Looks up an endpoint method, its parameters, response type, and a runnable code sample | "Show me how to call createOrder", "What does getTrack return?" | Method signature, parameter types, response type, and a copy-paste-ready code sample | + +End this section by telling the user that you'll demonstrate the four core discovery and +integration tools live during the tour, starting with `fetch_api` right now. Make it clear that +this tour is focused on those core ContextMatic server tools rather than every possible helper the +broader workflow might use. + + +--- + +## Phase 1 — Show available APIs + +### 1a. Detect the project language + +Before calling `fetch_api`, determine the project's primary language by inspecting workspace files: + +- Look for `package.json` + `.ts`/`.tsx` files → `typescript` +- Look for `*.csproj` or `*.sln` → `csharp` +- Look for `requirements.txt`, `pyproject.toml`, or `*.py` → `python` +- Look for `pom.xml` or `build.gradle` → `java` +- Look for `go.mod` → `go` +- Look for `Gemfile` or `*.rb` → `ruby` +- Look for `composer.json` or `*.php` → `php` +- If no project files are found, silently fall back to `typescript`. + +Store the detected language — you will pass it to every subsequent tool call. + +### 1b. Fetch available APIs + +Tell the user which language you detected and that you are fetching the available APIs — for +example: *"I can see this is a TypeScript project. Let me fetch the APIs available for TypeScript."* + +Call **`fetch_api`** with `language` = the detected language. + +Display the results as a formatted list, showing each API's **name** and a one-sentence summary of +its **description**. Do not truncate or skip any entry. + +Example display format (adapt to actual results): + +``` +Here are the APIs currently available through this server: + +1. PayPal Server SDK — Payments, orders, subscriptions, and vault via PayPal REST APIs. +2. Spotify Web API — Music/podcast discovery, playback control, and library management. +.... +``` + +--- + +## Phase 2 — API selection (interaction) + +Ask the user: + +> "Which of these APIs would you like to explore? Just say the name or the number." + +**Wait for the user's reply before continuing.** + +Store the chosen API's `key` value from the `fetch_api` response — you will pass it to all +subsequent tool calls. Also note the API's name for use in explanatory text. + +--- + +## Phase 3 — Explain the chosen API + +Before calling, say something like: *"Great choice — let me get an overview of [API name] for you."* + +Call **`ask`** with: +- `key` = chosen API's key +- `language` = detected language +- `query` = `"Give me a high-level overview of this API: what it does, what the main controllers or + modules are, how authentication works, and what the first step to start using it is."` + +Present the response conversationally. Highlight: +- What the API can do (use cases) +- How authentication works (credentials, OAuth flows, etc.) +- The main SDK controllers or namespaces +- The NPM/pip/NuGet/etc. package name to install + +--- + +## Phase 4 — Integration in the project language (interaction) + +Ask the user: + +> "Is there a specific part of the [API name] you want to learn how to use — for example, +> creating an order, searching tracks, or managing subscriptions? Or should I show you +> the complete integration quickstart?" + +**Wait for the user's reply.** + +Before calling, say something like: *"On it — let me look that up."* or *"Sure, let me pull up the quickstart."* + +Call **`ask`** with: +- `key` = chosen API's key +- `language` = detected language +- `query` = the user's stated goal, or `"Show me a complete integration quickstart: install the + SDK, configure credentials, and make the first API call."` if they asked for the full guide. + +Present the response, including any code samples exactly as returned. + +--- + +## Phase 5 — Demonstrate `model_search` + +Tell the user: + +> "Now let me show you how `model_search` works. This tool lets you look up any SDK model or +> object definition — its typed properties, which are required vs. optional, and what types they use. +> It works with partial, case-sensitive names." + +Before calling, say something like: *"Let me search for the `[model name]` model so you can see what the result looks like."* + +Pick a **representative model** from the chosen API (examples below) and call **`model_search`** with: +- `key` = the previously chosen API key (for example, `paypal` or `spotify`) +- `language` = the detected project language +- `query` = the representative model name you picked + +| API key | Good demo query | +|---|---| +| `paypal` | `Order` | +| `spotify` | `TrackObject` | + +Display the result, pointing out: +- The exact model name and its description +- A few interesting typed properties (highlight optional vs. required) +- Any nested model references (e.g., `PurchaseUnit[] | undefined`) + +Tell the user: + +> "You can search any model by name — partial matches work too. Try asking me to look up a +> specific model from [API name] whenever you need to know its shape." + +--- + +## Phase 6 — Demonstrate `endpoint_search` + +Tell the user: + +> "Similarly, `endpoint_search` looks up any SDK method — the exact parameters, their types, +> the response type, and a fully runnable code sample you can drop straight into your project." + +Before calling, say something like: *"Let me fetch the `[endpoint name]` endpoint so you can see the parameters and a live code sample."* + +Pick a **representative endpoint** for the chosen API and call **`endpoint_search`** with an explicit argument object: + +- `key`: the API key you are demonstrating (for example, `paypal` or `spotify`) +- `query`: the endpoint / SDK method name you want to look up (for example, `createOrder` or `getTrack`) +- `language`: the user's project language (for example, `"typescript"` or `"python"`) + +For example: + +| API key (`key`) | Endpoint name (`query`) | Example `language` | +|---|---|---| +| `paypal` | `createOrder` | user's project language | +| `spotify` | `getTrack` | user's project language | +Display the result, pointing out: +- The method name and description +- The request parameters and their types +- The response type +- The full code sample (present exactly as returned) + +Tell the user: + +> "Notice that the code sample is ready to use — it imports from the correct SDK, initialises +> the client, calls the endpoint, and handles errors. You can search for any endpoint by its +> method name or a partial case-sensitive fragment." + +--- + +## Phase 7 — Closing: what you can ask + +End the tour with a summary list of things the user can now ask the agent to do. Present this as +a formatted menu: + +--- + +### What you can do with this MCP + +**Quickstart: your first API call** +``` +/integrate-context-matic Set up the Spotify TypeScript SDK and fetch my top 5 tracks. +Show me the complete client initialization and the API call. +``` +``` +/integrate-context-matic How do I authenticate with the Twilio API and send an SMS? +Give me the full PHP setup including the SDK client and the send call. +``` +``` +/integrate-context-matic Walk me through initializing the Slack API client in a Python script and posting a message to a channel. +``` + +**Framework-specific integration** +``` +/integrate-context-matic I'm building a Next.js app. Integrate the Google Maps Places API +to search for nearby restaurants and display them on a page. Use the TypeScript SDK. +``` +``` +/integrate-context-matic I'm using Laravel. Show me how to send a Twilio SMS when a user +registers. Include the PHP SDK setup, client initialization, and the controller code. +``` +``` +/integrate-context-matic I have an ASP.NET Core app. Add Twilio webhook handling so I can receive delivery status callbacks when an SMS is sent. +``` + +**Chaining tools for full integrations** +``` +/integrate-context-matic I want to add real-time order shipping notifications to my +Next.js store. Use Twilio to send an SMS when the order status changes to "shipped". Show me +the full integration: SDK setup, the correct endpoint and its parameters, and the TypeScript code. +``` +``` +/integrate-context-matic I need to post a Slack message every time a Spotify track changes +in my playlist monitoring app. Walk me through integrating both APIs in TypeScript — start by +discovering what's available, then show me the auth setup and the exact API calls. +``` +``` +/integrate-context-matic In my ASP.NET Core app, I want to geocode user addresses using +Google Maps and cache the results. Look up the geocode endpoint and response model, then +generate the C# code including error handling. +``` + +**Debugging and error handling** +``` +/integrate-context-matic My Spotify API call is returning 401. What OAuth flow should I +be using and how does the TypeScript SDK handle token refresh automatically? +``` +``` +/integrate-context-matic My Slack message posts are failing intermittently with rate limit +errors. How does the Python SDK expose rate limit information and what's the recommended retry +pattern? +``` + +--- + +> "That's the tour! Ask me any of the above or just tell me what you want to build — I'll +> use this server to give you accurate, version-specific guidance." + +--- + +## Notes for the agent + +- If the user picks an API that is not in the `fetch_api` results, tell them it is not currently + available and offer to continue the tour with one that is. +- All tool calls in this skill are **read-only** — they do not modify the project, install packages, + or write files unless the user explicitly asks you to proceed with integration. +- When showing code samples from `endpoint_search` or `ask`, present them in fenced code blocks + with the correct language tag.