docs: adding Square MCP tutorial (#2405)

2025-12-17 14:14:26 +01:00 · 2025-04-30 16:48:06 -06:00
parent 3d4181fb38
commit 5882769ea5
3 changed files with 250 additions and 1 deletions
--- a/documentation/docs/tutorials/postgres-mcp.md
+++ b/documentation/docs/tutorials/postgres-mcp.md
@@ -186,7 +186,6 @@ Note that you'll need [Node.js](https://nodejs.org/) installed on your system to
  </TabItem>
 </Tabs>

-
 ## Example Usage

 The PostgreSQL extension enables you to query and analyze data or give you information about the table structures. The extension is only capable of *read-only* operations, so you can use it to get information about your database, but not to modify it.
--- a/documentation/docs/tutorials/square-mcp.md
+++ b/documentation/docs/tutorials/square-mcp.md
@@ -0,0 +1,250 @@
+---
+title: Square MCP Extension
+description: Add the Square API as a Goose Extension
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import YouTubeShortEmbed from '@site/src/components/YouTubeShortEmbed';
+
+This tutorial will get you started with the [official Square MCP Server](https://github.com/square/square-mcp-server) as a Goose extension to enable interactive work for your Square seller account!
+
+
+:::tip TLDR
+
+**Command**
+```sh
+npx -y square-mcp-server start
+```
+
+**Environment Variables**
+```
+ACCESS_TOKEN: <YOUR_API_KEY>
+SANDBOX: <true/false>
+PRODUCTION: <true/false>
+```
+
+Note that you'll use `SANDBOX` -or- `PRODUCTION`, not both, and your `ACCESS_TOKEN` will either be a sandbox or production token, depending on which environment you choose.
+:::
+
+## Configuration
+
+:::info
+Note that you'll need [Node.js](https://nodejs.org/) installed on your system to run this command, as it uses `npx`.
+:::
+
+<Tabs groupId="interface">
+  <TabItem value="ui" label="Goose Desktop" default>
+  1. [Launch the installer](goose://extension?cmd=npx&arg=-y&arg=square-mcp-server%20start&id=square-mcp&name=Square%20MCP%20Server&description=Square%20MCP%20Server&env=ACCESS_TOKEN%3DYour%20Access%20Token&env=SANDBOX%3Dtrue)
+  2. Press `Yes` to confirm the installation
+  3. Get your [Square Access Token](https://developer.squareup.com/apps) and paste it in
+  4. Keep `SANDBOX` as the environment variable, or change to `PRODUCTION`, and set its value to `true`
+  5. Click `Save Configuration`
+  6. Scroll to the top and click `Exit` from the upper left corner
+  </TabItem>
+  <TabItem value="cli" label="Goose CLI">
+  1. Run the `configure` command:
+  ```sh
+  goose configure
+  ```
+
+  1. Choose to add a `Command-line Extension`
+  ```sh
+    ┌   goose-configure 
+    │
+    ◇  What would you like to configure?
+    │  Add Extension 
+    │
+    ◆  What type of extension would you like to add?
+    │  ○ Built-in Extension 
+    // highlight-start    
+    │  ● Command-line Extension (Run a local command or script)
+    // highlight-end    
+    │  ○ Remote Extension 
+    └ 
+  ```
+
+  1. Give your extension a name
+  ```sh
+    ┌   goose-configure 
+    │
+    ◇  What would you like to configure?
+    │  Add Extension 
+    │
+    ◇  What type of extension would you like to add?
+    │  Command-line Extension 
+    │
+    // highlight-start
+    ◆  What would you like to call this extension?
+    │  square-mcp
+    // highlight-end
+    └ 
+  ```
+
+  1. Enter the command
+  ```sh
+    ┌   goose-configure 
+    │
+    ◇  What would you like to configure?
+    │  Add Extension 
+    │
+    ◇  What type of extension would you like to add?
+    │  Command-line Extension 
+    │
+    ◇  What would you like to call this extension?
+    │  square-mcp
+    │
+    // highlight-start
+    ◆  What command should be run?
+    │  npx -y square-mcp-server start
+    // highlight-end
+    └ 
+  ```  
+
+  1. Enter the number of seconds Goose should wait for actions to complete before timing out. Default is 300s
+   ```sh
+    ┌   goose-configure 
+    │
+    ◇  What would you like to configure?
+    │  Add Extension 
+    │
+    ◇  What type of extension would you like to add?
+    │  Command-line Extension 
+    │
+    ◇  What would you like to call this extension?
+    │  square-mcp
+    │
+    ◇  What command should be run?
+    │  npx -y square-mcp-server start
+    │
+    // highlight-start
+    ◆  Please set the timeout for this tool (in secs):
+    │  300
+    // highlight-end
+    │
+    └ 
+  ```  
+
+  1. Choose to add a description. If you select "Yes" here, you will be prompted to enter a description for the extension.
+   ```sh
+    ┌   goose-configure 
+    │
+    ◇  What would you like to configure?
+    │  Add Extension 
+    │
+    ◇  What type of extension would you like to add?
+    │  Command-line Extension 
+    │
+    ◇  What would you like to call this extension?
+    │  square-mcp
+    │
+    ◇  What command should be run?
+    │  npx -y square-mcp-server start
+    │
+    ◆  Please set the timeout for this tool (in secs):
+    │  300
+    │
+    // highlight-start
+    ◇  Would you like to add a description?
+    │  No
+    // highlight-end
+    │
+    └ 
+  ```  
+
+  1. Obtain a [Square Access Token](https://developer.squareup.com/apps) and paste it in.
+   ```sh
+    ┌   goose-configure 
+    │
+    ◇  What would you like to configure?
+    │  Add Extension 
+    │
+    ◇  What type of extension would you like to add?
+    │  Command-line Extension 
+    │
+    ◇  What would you like to call this extension?
+    │  square-mcp
+    │
+    ◇  What command should be run?
+    │  npx -y square-mcp-server start
+    │
+    ◇  Please set the timeout for this tool (in secs):
+    │  300
+    │
+    ◇  Would you like to add a description?
+    │  No
+    │
+    // highlight-start
+    ◆  Would you like to add environment variables?
+    │  Yes 
+    │
+    ◇  Environment variable name:
+    │  ACCESS_TOKEN
+    │
+    ◇  Environment variable value:
+    │  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
+    │
+    ◇  Add another environment variable?
+    │  Yes
+    │
+    ◇  Environment variable name:
+    │  SANDBOX
+    │
+    ◇  Environment variable value:
+    │  true
+    // highlight-end
+    └  Added square-mcp extension
+  ```  
+    :::info 
+    Change the `SANDBOX` key to `PRODUCTION` if using a production token
+    :::
+
+  </TabItem>
+</Tabs>
+
+## Example Usage
+
+The Square MCP server allows you to interact with Square's connect API with an extensive [service catalog](https://github.com/square/square-mcp-server?tab=readme-ov-file#service-catalog) to access the Square API ecosystem.
+
+#### Goose Prompt
+
+```
+( O)> Find my food menu from the following image and import these into my Square seller account. "my-burger-menu.png"
+```
+
+[Here's the menu image used in the demo.](../assets/guides/square-mcp-goosin-menu.png)
+
+#### Goose Output
+
+```
+I'll help you import these menu items into your Square catalog. I'll use the Square API to create catalog items for each burger. Let me break this down into steps:
+
+1. First, I'll check the catalog API service info and types
+2. Then I'll create catalog items for each burger
+
+Now let me check the type info for creating catalog objects
+
+Now I'll start creating catalog items for each burger in your menu. I'll create them one by one using the catalog API. Let me process each burger:
+
+(output truncated)
+
+I've successfully created all the burger items from your menu in your Square catalog. Each burger has been added with:
+
+- The exact name from your menu
+- The full description
+- The correct price
+- A standard variation for ordering
+
+Here's a summary of what was created:
+- The Classic - $10.00
+- Cheeseburger - $11.00
+- Primetime Burger - $12.00
+- Double Bacon - $14.00
+- Texas Meatlover - $12.50
+- Buffalo Burger - $12.00
+- The Atomic - $12.50
+- Little Bird - $11.00
+- Mushroom Burger - $10.00
+
+All items are now available in your Square catalog and ready for use in your point of sale system. Each burger includes its complete description and comes with a "Regular" variation at the specified price. The items are set as both sellable and stockable by default, and they're available at all locations.
+```