npm package: @passelin/mcp-server-speak
Description: A MCP server that provides the ability to speak text using the system's text-to-speech engine.
Author: Pierre Asselin
Latest version: 1.0.0

# @passelin/mcp-server-speak

A [Model Context Protocol (MCP)](https://github.com/microsoft/modelcontextprotocol) server that provides the ability to speak text using the system's text-to-speech engine.

## Features

- Converts text to speech using the system's native text-to-speech capabilities (uses the `say` package)
- Supports customizable voices (when available on your system)
- Adjustable speech speed
- Ability to stop speech mid-playback
- Uses stdio transport

## Installation

```bash
npm install @passelin/mcp-server-speak
```

Or install globally:

```bash
npm install -g @passelin/mcp-server-speak
```

## Usage

### Starting the Server

Start the MCP server:

```bash
npx @passelin/mcp-server-speak
```

If installed globally:

```bash
mcp-server-speak
```

### Using as a Library

You can also use this package as a dependency in your own MCP-compatible project:

```javascript
import { spawn } from "child_process";

// Spawn the MCP server process
const mcpServer = spawn("npx", ["@passelin/mcp-server-speak"], {
  stdio: ["pipe", "pipe", "inherit"],
});

// Send a request to speak text
const request = {
  jsonrpc: "2.0",
  id: "123",
  method: "tools/call",
  params: {
    name: "speak",
    arguments: {
      text: "Hello world! This is a test message spoken through the MCP server.",
    },
  },
};

mcpServer.stdin.write(JSON.stringify(request) + "\n");
```

## API

This MCP server provides the following tools:

### 1. `speak`

Speaks the provided text using the system's text-to-speech engine.

Parameters:

- `text` (string, required): The text to speak
- `voice` (string, optional): Optional voice to use for speech (depends on available system voices)
- `speed` (number, optional): Speed of speech (defaults to 1.0)

Example request:

```json
{
  "jsonrpc": "2.0",
  "id": "123",
  "method": "tools/call",
  "params": {
    "name": "speak",
    "arguments": {
      "text": "Hello! This is a test message.",
      "voice": "Alex",
      "speed": 1.2
    }
  }
}
```

### 2. `stop`

Stops any ongoing speech.

Parameters: None

Example request:

```json
{
  "jsonrpc": "2.0",
  "id": "456",
  "method": "tools/call",
  "params": {
    "name": "stop",
    "arguments": {}
  }
}
```

## Quick Test

Test the server with a simple command:

```bash
npm run test:quick
```

This will send a test message to be spoken through the MCP server.

## Running Tests

To run comprehensive tests:

```bash
npm test
```

This will:

1. Build the project
2. Start the MCP server
3. Run several test cases for different features
4. Generate a test report

## Development

### Prerequisites

- Node.js 18.0.0 or higher
- npm 7.0.0 or higher

### Setting Up the Development Environment

```bash
# Clone the repository
git clone https://github.com/your-username/mcp-server-say.git
cd mcp-server-say

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

### Scripts

- `npm run build`: Compiles TypeScript to JavaScript
- `npm run start`: Starts the MCP server
- `npm run dev`: Builds and starts the server in development mode
- `npm run test`: Runs comprehensive tests for all features

## Dependencies

- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk): Model Context Protocol SDK
- [say](https://www.npmjs.com/package/say): A simple text-to-speech library for Node.js
- [zod](https://www.npmjs.com/package/zod): TypeScript-first schema validation library

## License

This project is licensed under the MIT License.

## Author

Pierre Asselin <pierre@asselin.info>