MCP Custom Server Tools + Amazon-Q. How to ...?

Hey fellow reader!
It is me again , the one that always tries to catch the running train.
Once I tasted the power of MCP protocol, I wanted more...
And here it is, short post about how to implement and use MCP tools with Amazon-Q or any other client.
If you have followed my previous post on how to implement MCP custom server this one, you can use the same project and we can get going from there.
Few words on what MCP Server tools are :
There is an excellent documentation MCP protocol tools, and in short, and as a really high overview - Tools as primitives of MCP protocol allow the server to expose executable functionality to clients.
In our case, with a custom server, it would mean that we would be able to ask our LLM client in a natural language to look into our custom server, find the tool and execute it. Wow!
Lets get to work...
We have our MCP custom server exposing resources and connected to Amazon-Q, all what we need to do is to add new capability: tools.
Our tool will be able to generate image file from a flowchart created with mermaid markdown. We will be using mermaid.js API call to generate output image from input mermaid markdown. Mermaid API Usage Cool!

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import {run} from '@mermaid-js/mermaid-cli';
import fs from 'fs/promises';

const server = new Server({
    name: 'docs-demo',
    version: '1.0.0'
    }, {
        capabilities: {
            resources: {},
            tools: {}
        }
    }
);

Again we will use low-server methods to create our tool. Add this to index.ts

server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
        tools: [{
            name: 'flow-chart',
            description: 'Display flow chart with mermaid',
            inputSchema: {
                type: 'object',
                properties: {
                   input: {type: 'string'},
                   output: {type: 'string'}
                },
                required: ['input', 'output']
            },
             annotations: {
                title: "Flow chart views",
            }
        },
    ]
}
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name === 'flow-chart') {
        const input = request.params.arguments?.input as string;
        const output = request.params.arguments?.output as `${string}.png` | `${string}.md` | `${string}.markdown` | `${string}.svg` | `${string}.pdf`;

        await run(input, output)
        return {
            content: {
                uri: 'file://' + `${output}`,
                type: 'image/png'
            }
        }
    }
    throw new Error('Tool not found');
})

Now we need to check if our client Amazon-Q is connected to our server and would be able to find our server tool.

In the terminal type this after starting the client with q chat:

/tools

you should be able to see this:

Note: for this example we are interested in the flowchart tool.
Now lets ask our client Amazon-Q in a natural language to generate image in a specified directory from a flowchart.md located in our docs folder using our custom MCP server's tool flowchart.
could you generate image file from ./src/docs/flowchart.md in ./src/assets/chart.png using flowchart tool from mcp server.
You should be able to see this:

type t in the terminal to confirm you trust your tool and to allow further actions.
And there we have it:

I am extremely excited about what the future holds.
Thank you for reading. I am beyond grateful for your time and will appreciate your comments and feedback highly.
Can not wait to find out, what awesome tools you have built, using MCP protocol and custom server.
Happy building!