Add documentation for MCP usage with Gordon

Signed-off-by: Djordje Lukic <[email protected]>

Author: rumpl

content/manuals/desktop/features/gordon.md renamed to content/manuals/desktop/features/gordon/_index.md

@@ -0,0 +1,148 @@
+---
+title: MCP
+description: Best practices for using Docker Desktop with WSL 2
+keywords: ai, mcp, gordon
+---
+
+
+> **tldr:** Gordon supports containerised MCP servers, at the root of your source tree, create a `gordon-mcp.yml` which is a standard compose file, and Gordon will enrich its response leveraging the servers described in that file.
+> 
+
+## What is MCP?
+
+Anthropic recently announced the [Model Context Protocol](https://www.anthropic.com/news/model-context-protocol) (MCP) specification, an open protocol that standardises how applications provide context to large language models. MCP functions as a client-server protocol, where the client (e.g., an application like Gordon) sends requests, and the server processes those requests to deliver the necessary context to the AI.
+
+Gordon, along with other MCP clients like Claude Desktop, can interact with MCP servers running as containers. Docker has partnered with Anthropic to build container images for the [reference implementations](https://github.com/modelcontextprotocol/servers/) of MCP servers, available on Docker Hub under [the mcp namespace](https://hub.docker.com/u/mcp).
+
+## Simple MCP server usage with Gordon
+
+When you run the `docker ai` command in your terminal to ask a question, Gordon will look for a `gordon-mcp.yml` file for a list of MCP servers that should be used when in that context. The `gordon-mcp.yml` file is a Docker Compose file that configures MCP servers as Compose services for Gordon to access.
+
+As a minimal example, let’s take a look at how you can use the [mcp-time server](https://hub.docker.com/r/mcp/time) to provide temporal capabilities to Gordon. (Source code and documentation is available [here](https://github.com/modelcontextprotocol/servers/tree/main/src/time)).
+
+1. Create the `gordon-mcp.yml` file and add the time sever:
+    
+    ```yaml
+    services:
+      time:
+        image: mcp/time
+    ```
+    
+2. With this file you can now ask Gordon to tell you the time in another timezone:
+    
+    ```bash
+    $ docker ai 'what time is it now in kiribati?'
+    
+        • Calling get_current_time
+    
+      The current time in Kiribati (Tarawa) is 9:38 PM on January 7, 2025.
+    
+    ```
+    
+
+As you can see, Gordon found the MCP time server and called its tool when needed.
+
+## Advanced usage
+
+Some MCP servers need access to your filesystem, or system environment variables. Docker Compose can help with this. Since `gordon-mcp.yml` is a Compose file you can add bind mounts using the regular Docker Compose syntax, which will make your filesystem resources available to the container:
+
+```yaml
+services:
+  fs:
+    image: mcp/filesystem
+    command:
+      - /rootfs
+    volumes:
+      - .:/rootfs
+```
+
+This `gordon-mcp.yml` file adds filesystem access capabilities to Gordon, since everything runs inside a container Gordon will only **have access to the directories you specify.
+
+Gordon can handle any number of MCP servers, for example we can give Gordon access to the internet with the `mcp/fetch` server:
+
+```yaml
+services:
+  fetch:
+    image: mcp/fetch
+  fs:
+    image: mcp/filesystem
+    command:
+      - /rootfs
+    volumes:
+      - .:/rootfs
+```
+
+We can now combine these and ask things like
+
+```bash
+$ docker ai can you fetch rumpl.dev and write the summary to a file test.txt 
+
+    • Calling fetch ✔️
+    • Calling write_file ✔️
+    • Calling list_allowed_directories ✔️
+    • Calling write_file ✔️
+  
+  The summary of the website rumpl.dev has been successfully written to the file test.txt in the allowed directory. Let me know if you need further assistance!
+  
+  
+$ cat test.txt 
+The website rumpl.dev features a variety of blog posts and articles authored by the site owner. Here's a summary of the content:
+
+1. **Wasmio 2023 (March 25, 2023)**: A recap of the WasmIO 2023 conference held in Barcelona. The author shares their experience as a speaker and praises the organizers for a successful event.
+
+2. **Writing a Window Manager in Rust - Part 2 (January 3, 2023)**: The second part of a series on creating a window manager in Rust. This installment focuses on enhancing the functionality to manage windows effectively.
+
+3. **2022 in Review (December 29, 2022)**: A personal and professional recap of the year 2022. The author reflects on the highs and lows of the year, emphasizing professional achievements.
+
+4. **Writing a Window Manager in Rust - Part 1 (December 28, 2022)**: The first part of the series on building a window manager in Rust. The author discusses setting up a Linux machine and the challenges of working with X11 and Rust.
+
+5. **Add docker/docker to your dependencies (May 10, 2020)**: A guide for Go developers on how to use the Docker client library in their projects. The post includes a code snippet demonstrating the integration.
+
+6. **First (October 11, 2019)**: The inaugural post on the blog, featuring a simple "Hello World" program in Go.%   
+
+```
+
+## What’s next?
+
+Now that you’ve learned how to use MCP servers with Gordon, here are a few ways you can get started:
+
+- Experiment with MCP servers: Try integrating one or more of the tested MCP servers into your `gordon-mcp.yml` file and explore their capabilities.
+1. Explore the MCP ecosystem: Check out the [reference implementations on GitHub](https://github.com/modelcontextprotocol/servers/) or browse the [Docker Hub MCP namespace](https://hub.docker.com/u/mcp) for additional servers that might suit your needs.
+2. Build your own MCP server: If none of the existing servers meet your needs, or you’re curious about exploring how they work in more detial, consider developing a custom MCP server. Use the [MCP specification](https://www.anthropic.com/news/model-context-protocol) as a guide.
+3. Share your feedback: If you discover new servers that work well with Gordon or encounter issues with existing ones, [share your findings to help improve the ecosystem.](https://docker.qualtrics.com/jfe/form/SV_9tT3kdgXfAa6cWa)
+
+With MCP support, Gordon offers powerful extensibility and flexibility to meet your specific use cases. Whether you’re adding temporal awareness, file management, or internet access, the possibilities are endless.
+
+### List of known working MCP Servers
+
+These are the MCP servers that we have tested successfully with Gordon
+
+- `mcp/time`
+- `mcp/fetch`
+- `mcp/filesystem`
+- `mcp/postgres`
+- `mcp/git`
+- `mcp/sqlite`
+- `mcp/github`
+
+### List of MCP servers we are not sure about
+
+These are the MCP servers that we have not tested but should work if given the appropriate tokens
+
+- `mcp/brave-search`
+- `mcp/gdrive`
+- `mcp/slack`
+- `mcp/google-maps`
+- `mcp/gitlab`
+- `mcp/everything`
+- `mcp/aws-kb-retrieval-server`
+- `mcp/sentry`
+
+### List of MCP servers that don’t work with Gordon
+
+These are the MCP servers that we know don’t work and why
+
+- `mcp/sequentialthinking` - The tool description is too long
+- `mcp/puppeteer` - Puppeteer send back images and Gordon doesn’t know how to handle them, it only handles text responses from tools
+- `mcp/everart` - Everart send back images and Gordon doesn’t know how to handle them, it only handles text responses from tools
+- `mcp/memory` - There is no way to configure the server to use a custom path for its knowledge base

content/manuals/desktop/features/gordon/mcp.md

@@ -45,7 +45,7 @@ Using the `admin-settings.json` file, you can:
 - Turn off Docker Extensions
 - Turn off Docker Scout SBOM indexing
 - Turn off beta and experimental features
-- Turn off Docker AI ([Ask Gordon](../../../../desktop/features/gordon.md))
+- Turn off Docker AI ([Ask Gordon](../../../../desktop/features/gordon/_index.md))
 - Turn off Docker Desktop's onboarding survey
 - Control whether developers can use the Docker terminal
 - Control the file sharing implementation for your developers on macOS