# 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

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Build the project:**
   ```bash
   npm run build
   ```

3. **Start the server:**
   ```bash
   npm start
   ```

## Development

For development with auto-rebuild and restart:

```bash
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:

1. Add the tool definition in the `ListToolsRequestSchema` handler
2. Add the tool implementation in the `CallToolRequestSchema` handler
3. Rebuild and test

Example tool addition:

```typescript
// 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:

1. Build and ensure the server runs correctly
2. Configure the server in your Q CLI MCP settings
3. 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.