MCP Server Scaffold

A basic scaffolding project for building Model Context Protocol (MCP) servers.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). MCP enables secure, controlled interactions between AI systems and various data sources and tools.

Features

This scaffold provides:

✅ Basic MCP server implementation
✅ Sample tools (echo, get_current_time)
✅ TypeScript support with proper types
✅ Error handling and logging
✅ Standard MCP protocol compliance
✅ Development and build scripts

Setup

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Start the server:
```
npm start
```

Development

For development with auto-rebuild and restart:

npm run dev

Available Tools

echo

Echoes back the provided message.

Parameters:

message (string, required): The message to echo back

get_current_time

Returns the current date and time in ISO format.

Parameters: None

Project Structure

mcp-server-scaffold/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Extending the Server

To add new tools:

Add the tool definition in the ListToolsRequestSchema handler
Add the tool implementation in the CallToolRequestSchema handler
Rebuild and test

Example tool addition:

// In ListToolsRequestSchema handler
{
  name: 'my_new_tool',
  description: 'Description of what the tool does',
  inputSchema: {
    type: 'object',
    properties: {
      param1: {
        type: 'string',
        description: 'Description of parameter',
      },
    },
    required: ['param1'],
  },
}

// In CallToolRequestSchema handler
case 'my_new_tool':
  // Your tool implementation here
  return {
    content: [
      {
        type: 'text',
        text: `Result: ${args.param1}`,
      },
    ],
  };

Integration with Q CLI

To use this MCP server with Amazon Q CLI:

Build and ensure the server runs correctly
Configure the server in your Q CLI MCP settings
The tools will be available as mcp-server-scaffold___tool-name

Error Handling

The server includes comprehensive error handling:

Tool execution errors are caught and returned as error responses
Server errors are logged to stderr
Graceful shutdown on SIGINT

License

MIT License - feel free to use this scaffold as a starting point for your own MCP servers.

Project Structure

mcp-server-scaffold/ ├── src/ │ └── index.ts # Main server implementation ├── dist/ # Compiled JavaScript (generated) ├── package.json # Project configuration ├── tsconfig.json # TypeScript configuration └── README.md # This file

Extending the Server

To add new tools:

Add the tool definition in the ListToolsRequestSchema handler

Add the tool implementation in the CallToolRequestSchema handler

Rebuild and test

Example tool addition:

// In ListToolsRequestSchema handler { name: 'my_new_tool', description: 'Description of what the tool does', inputSchema: { type: 'object', properties: { param1: { type: 'string', description: 'Description of parameter', }, }, required: ['param1'], }, } // In CallToolRequestSchema handler case 'my_new_tool': // Your tool implementation here return { content: [ { type: 'text', text: `Result: ${args.param1}`, }, ], };