DEV Community

Cover image for Custom MCP Server + Amazon Q - Powerhouse combination
AWS Community Builders profile image Denise Ignatova
Denise Ignatova for AWS Community Builders

Posted on • Edited on

Custom MCP Server + Amazon Q - Powerhouse combination

#ai #mcp #programming

Hey fellow reader!
I hope am not too late for the MCP party, and I hope with this short post to add meaningful contribution to the already awesome resources out there.
In short:
I have decided to try out building custom MCP server which exposes as a resource specific documentation and connect it Amazon Q.
I have used typescript sdk Link here.
Lets get started then!

  • create a directory 
mkdir mcp-server
Enter fullscreen mode Exit fullscreen mode

(side note: I am using pnpm, as package manager)

  • inside the newly created directory run 
pnpm init
Enter fullscreen mode Exit fullscreen mode

to generate package.json file. Once it is generated, navigate to it and replace script section with :

script: {
    "build": "tsc && chmod 755 build/index.js"
  }
Enter fullscreen mode Exit fullscreen mode

you are pointing typescript where to store your public endpoint , giving the necessary permission too. After that you would need to create your tsconfig.json.

tsc init
Enter fullscreen mode Exit fullscreen mode

make the needed changes:

  • outDir: './build'

  • target: 'es2022'

  • module: 'NodeNext'

last two would allow top level await to be used.
Install @modelcontextprotocol/sdk.

We will be using low-level server. Examples from the mcp repository : Low-level mcp-server.
We can start.
Create a src directory and inside it create a file called index.ts

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import * as fs from 'node:fs/promises';
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

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

const docFiles = await fs.readFile('./src/docs/integration.md');
server.setRequestHandler(ListResourcesRequestSchema, async () => {
    return {
        resources:[
            {
            uri: 'file://' + __dirname + '/docs/integration.md',
            name: 'Integration docs',
            mimeType: 'text/plain'
            }
        ]
    }
});

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
    const uri = request.params.uri;
    if (uri === 'file://' + __dirname + '/docs/integration.md') {
        return {
            contents: [
                {
                    uri,
                    mimeType: 'text/plain',
                    text: docFiles.toString('utf-8')
                }

            ]
        }
    }
    throw new Error('Resource not found');
});


const transposrt = new StdioServerTransport();
console.log('Starting server...');
await server.connect(transposrt)
Enter fullscreen mode Exit fullscreen mode

Create a docs folder in you src folder. There we will add our integration.md file. You would need an assets folder with our diagram. You can download this one!

Image description

content of integratiion.md file

# Integration awesome105
### Build a simple flow with AWS SQS , AWS SNS and AWS Lambda

![Diagram](../assets/image.png)
Enter fullscreen mode Exit fullscreen mode

Now we need to install Amazon-q CLI. Here is an excellent tutorial how to install amazon-q on a different os systems.
Link to the tutorial

I have used:

brew install amazon-q
Enter fullscreen mode Exit fullscreen mode

After installation check if it is installed:

q version
Enter fullscreen mode Exit fullscreen mode

Now comes the most important part. To let know amazon-q that there is a mcp-server. Amazon-q will be installed in a directory ~/.aws/amazonq. Get into this directory like this:

cd ~/.aws/amazonq
Enter fullscreen mode Exit fullscreen mode

Now type ls to list everything in this directory - should not have mcp.json. Type in the terminal:

touch mcp.json
Enter fullscreen mode Exit fullscreen mode

copy and paste this and save:

{
  "mcpServers": {
    "docs-demo": {
      "command": "node", // command that will run your index.js
      "args": [
        "/absolute_path/build/index.js"] //absolute path to your index.js
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Now time to test!
Go back to your terminal and type q chat. You should be able to see this ....

Image description

Now lets ask amazon-q to find documentation for our awesome105 integration and explain the diagram associated with it.

And voila...

Image description

This is truly amazing! Could you imagine what horizons this feature opens? For me beyond my dreams! Thank you Amazon-q!
Thank you for reading! Please leave a comment and let me know what cool projects you came up with using mcp-server and amazon-q!

Top comments (1)

Collapse
 
mgbec profile image
mgbec •

Great article- thank you for sharing, Denise!