Update docs

Author: slimslenderslacks

docs/content/tools/docs/_index.md

@@ -4,8 +4,10 @@ title: Documentation
 
 ### Topics
 
-* [How to author prompts](prompts)
+* [How to author prompts](authoring-prompts)
 * [Updating Claude Desktop](claude-desktop)
 * [Adding to the catalog](adding-to-catalog)
+* [mcp/docker container logs](mcp-server)
+* [Using from docker ai (Gordon)](gordon)
 
 

docs/content/tools/docs/adding-to-catalog.md

@@ -1,4 +1,6 @@
-# Adding to Catalog
+---
+title: Adding to Catalog
+---
 
 Once you have published a prompt to a publicly accessible git repository, you can submit a PR to add it to the catalog.
 
@@ -10,3 +12,7 @@ Once you have published a prompt to a publicly accessible git repository, you ca
   icon: <prompt-icon> # Required URL to icon
   ref: <prompt-ref> # Required ref to prompt. Format: <provider>:<repo>?ref=<ref>&path=<path> example: github:docker/labs-ai-tools-for-devs?ref=main&path=prompts/examples/mcp-sqlite.md
 ```
+
+* choose a unique `<prompt-name>`
+* the `<prompt-ref>` must be a valid github reference uri, which is of the form `github:<org-name>/<repo-name>?path=relative/path/to/file.md` (you can refer to a branch 
+  by adding another query parameter `&ref=<branch-name>`)

docs/content/tools/docs/authoring-prompts.md

@@ -121,22 +121,56 @@ contain template parameters.
 For example, the above curl example could be re-written as a template with a ``{{ user }}`` parameter.
 
 ```markdown
----
+---yaml
 tools:
   - name: curl
 url:  http://localhost/v1/chat/completions
 stream: false
 model: llama3.1
+arguments:
+  - name: user
+    description: the GitHub username to fetch gists for
+    required: true
 ---
 
 # prompt
 
 Run the curl command, in silent mode, to fetch gists for user {{ user }} from GitHub.
 ```
 
+### Template Engine
+
+We support two templating engines today.
+
+* [mustache](https://mustache.github.io/mustache.5.html) is the default
+* [django](https://docs.djangoproject.com/en/5.1/topics/templates/)
+
+If you want to use django, then add the following field in the markdown preamble.
+
+```markdown
+---
+prompt-format: "django"
+arguments:
+  - name: user
+    description: the GitHub username to fetch gists for
+    required: true
+---
+```
+
+### MCP arguments
+
+MCP clients can use `arguments` to help you bind values into templates.
+
+```yaml
+---
+prompt-format: "django"
+---
+```
+
 ### Binding values during testing
 
-When running in VSCode, you can set values of the parameters in the markdown preamble.
+When running in VSCode, you can set values of the parameters in the markdown preamble. This is
+a great way to quickly test your prompt during development.
 
 ```markdown
 ---
@@ -186,22 +220,3 @@ This project contains {{language}} code.
 
 ```
 
-### Template Engine
-
-We support two templating engines today.
-
-* [mustache](https://mustache.github.io/mustache.5.html) is the default
-* [django](https://docs.djangoproject.com/en/5.1/topics/templates/)
-
-If you want to use django, then add the following field in the markdown preamble.
-
-```markdown
----
-prompt-format: "django"
----
-```
-
-### MCP arguments
-
-
-

docs/content/tools/docs/claude-desktop.md

@@ -23,22 +23,25 @@ Enable mcp_run in your claude_desktop_config.json file using the following snipp
 }
 ```
 
-Notice in the above snippet that the server is loaded with one example prompt, which you can view in our [public github repo](https://github.com/docker/labs-ai-tools-for-devs/blob/main/prompts/examples/hello_world.md?plain=1).
-This will have already been exposed using this MCP server so when using Claude Desktop, you can type "use hello docker to greet me with a joke".
+## Adding Tools
 
-You'll see a prompt asking if you want to run the "hello world" tool locally.
-
-![consent](consent.png)
+Install the [`docker/labs-ai-tools-for-devs` extension](https://open.docker.com/extensions/marketplace?extensionId=docker/labs-ai-tools-for-devs) to
+see a catalog of tools that you can install into the server.
 
-## More prompts
-
-You can register new definitions in public github repos by adding additional `--register` arguments.
+You can also register new tool definitions by adding `--register` arguments to the above server definition.
 
 ```
         "--register", "github:docker/labs-ai-tools-for-devs?path=prompts/examples/swagger.md"
 ```
 
-We are moving these registration command to a command line. It doesn't make sense to change the claude 
-config each time you add or remote a defintion.  However, because Claude Desktop has to be restarted 
-every time a definition changes today (because of the missing notification), we will work
-with Anthropic to make this much smoother.
+Learn more about the tool definitions being referenced here using the page on [authoring the tool definitions](../authoring-prompts).
+
+## Try a sample tool
+
+Try activating thel _hello world_ tool in our catalog (here's the [definition](https://github.com/docker/labs-ai-tools-for-devs/blob/main/prompts/examples/hello_world.md?plain=1) )
+and then type "use hello docker to greet me with a joke".
+
+You'll see a prompt asking if you want to run the "hello world" tool locally.
+
+![consent](consent.png)
+

docs/content/tools/docs/gordon.md

@@ -0,0 +1,30 @@
+---
+title: Using with Gordon
+---
+
+## gordon-mcp.yaml
+
+When you run `docker ai` from any directory, docker ai will search that directory for a gordon-mcp.yml file.
+If that file is present, and configured with the `mcp/docker` container then Gordon will load tools from
+this container and try to use them.
+
+```yaml
+services:
+  mcp_docker:
+    image: mcp/docker:latest
+    command: serve --mcp --register github:docker/labs-ai-tools-for-devs?path=prompts/bootstrap.md
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - docker-prompts:/prompts
+    x-mcp-autoremove: true
+
+volumes:
+  docker-prompts:
+    external: true
+```
+
+## debugging
+
+We suggest using `docker ai --debug` if you are trying to debug some of your tools while using the `docker ai` cli.
+
+

docs/content/tools/docs/mcp-server.md

@@ -1,5 +1,5 @@
 ---
-title: running the mcp/docker image
+title: mcp/docker server logs
 ---
 
 ## Logging

docs/content/tools/quickstart.md

@@ -9,7 +9,7 @@ weight: 1
 
 ## Quick Start w/ Docker Desktop Extension
 
-1. Install [Docker Labs AI Tools for Devs](https://hub.docker.com/extensions/docker/labs-ai-tools-for-devs)
+1. Install [Docker Labs AI Tools for Devs](https://open.docker.com/extensions/marketplace?extensionId=docker/labs-ai-tools-for-devs)
 2. Click on the Claude button to add `mcp_docker` toolbox to your Claude Desktop.
 3. Select any prompts you would like to add from the catalog to your toolbox.
 
@@ -23,8 +23,8 @@ currently have to restart desktop more less continuously. Fire up those keybinds
 
 ### Try a prompt
 
-Write a prompt in Claude that will run one of the tools in a registered defintion.
-For example:
+Type an instruction to Claude that will use one of the tools you've added.
+For example, if you've enabled the _hello world_ tool, then you could type the following.
 
 > Use hello world to send a greeting and then respond to what comes back.
 

docs/hugo.yaml

@@ -13,3 +13,6 @@ markup:
   goldmark:
     renderer:
       unsafe: true
+params:
+  search:
+    enable: false

prompts/examples/mcp-sqlite.md

@@ -75,6 +75,10 @@ tools:
 prompt-format: django
 parameter-values:
   topic: Ocean Conservation
+arguments:
+  - name: topic
+    description: The topic for the business scenario
+    required: true
 ---
 
 # prompt user