# MCP Unix Manual

A Model Context Protocol (MCP) server that provides access to Unix manual pages directly within Claude. Query man pages, search documentation, and explore Unix commands without leaving your conversation.

## Features

- **Read Manual Pages**: Get the full text of any Unix man page
- **Search Documentation**: Find commands by keyword using `apropos`
- **Browse Sections**: Explore the standard Unix manual page sections
- **macOS Native**: Built with Swift for optimal performance on macOS

## Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `read_manpage` | Read a Unix manual page | `command` (required), `section` (optional) |
| `search_manpages` | Search man pages by keyword | `query` (required) |
| `list_man_sections` | List standard manual sections | None |

### Example Usage

```
Claude, can you read the man page for grep?
Claude, search for commands related to "network"
Claude, show me the list of manual sections
```

## Requirements

- macOS 13.0 or later
- Swift 6.2 or later
- Xcode (for building)

## Installation

### 1. Build the Server

Clone the repository and build a release version:

```bash
git clone <repository-url>
cd MCPUnixManual
swift build -c release
```

The executable will be located at `.build/release/mcp-unix-manual`.

### 2. Configure Claude Desktop

#### Step 1: Locate the Configuration File

Open the Claude Desktop configuration file:

```bash
open ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

If the file doesn't exist, create it:

```bash
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

#### Step 2: Add the MCP Server

Add the following configuration to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "unix-manual": {
      "command": "/absolute/path/to/MCPUnixManual/.build/release/mcp-unix-manual"
    }
  }
}
```

**Important**: Replace `/absolute/path/to/MCPUnixManual` with the actual absolute path to your cloned repository.

To find the absolute path, run this in your project directory:

```bash
pwd
```

Then use that path in your configuration. For example:

```json
{
  "mcpServers": {
    "unix-manual": {
      "command": "/Users/yourname/Projects/MCPUnixManual/.build/release/mcp-unix-manual"
    }
  }
}
```

#### Step 3: Restart Claude Desktop

Completely quit and restart Claude Desktop for the changes to take effect.

#### Step 4: Verify Integration

Open Claude Desktop and look for the MCP icon (🔌) in the bottom right corner. Click it to see available MCP servers - you should see "unix-manual" listed.

You can now ask Claude to use the Unix manual tools:
- "Read the man page for `ls`"
- "Search for commands related to processes"
- "What are the Unix manual sections?"

### Troubleshooting

**MCP server not appearing:**
- Verify the path in `claude_desktop_config.json` is absolute and correct
- Check that the executable has execute permissions: `chmod +x .build/release/mcp-unix-manual`
- Ensure you've restarted Claude Desktop completely

**Permission errors:**
- Make sure the executable is built and accessible
- Try running the executable directly to check for errors: `.build/release/mcp-unix-manual`

**JSON syntax errors:**
- Validate your `claude_desktop_config.json` syntax
- Ensure there are no trailing commas in the JSON

## Claude Code Integration

For Claude Code (CLI), add the following to your MCP settings file:

```json
{
  "mcpServers": {
    "unix-manual": {
      "command": "/absolute/path/to/MCPUnixManual/.build/release/mcp-unix-manual"
    }
  }
}
```

## Development

### Running in Development Mode

```bash
swift run mcp-unix-manual
```

### Running Tests

```bash
swift test
```

### Project Structure

```
MCPUnixManual/
├── Package.swift              # Swift package manifest
├── Sources/
│   └── MCPUnixManual/
│       └── MCP.swift         # Main server implementation
└── README.md
```

## Security

This MCP server executes shell commands (`man`, `apropos`) to retrieve Unix manual pages. Input validation is performed to prevent command injection:

- Only alphanumeric characters, dots, hyphens, and underscores are allowed in command names
- Arguments are properly escaped before execution
- Commands run with the same permissions as Claude Desktop

## Platform Support

- **macOS**: Full support (uses `Foundation.Process`)
- **iOS/tvOS/watchOS/visionOS**: Compiles but returns error messages (Process unavailable)

This is intentional - Unix manual pages are only available on macOS.

## License

[Add your license here]

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Credits

Built with the [MCP Swift SDK](https://github.com/modelcontextprotocol/swift-sdk) by Anthropic.