# Simple Model Context Protocol (MCP) Server

A simple MCP server that provides basic utility tools for text manipulation, file operations, and calculations. This server can be connected to Claude AI desktop app to extend its capabilities.

## Features

### Available Tools:
- **echo**: Echo back any text you provide
- **calculate**: Perform basic mathematical calculations
- **word_count**: Count words, characters, and lines in text
- **reverse_text**: Reverse any text string
- **uppercase**: Convert text to uppercase
- **list_files**: List files and directories
- **get_system_info**: Get basic system information

## Quick Setup

1. **Run the setup script:**
   ```bash
   ./setup.sh
   ```

2. **Or manual setup:**
   ```bash
   # Create virtual environment
   python3 -m venv venv
   source venv/bin/activate
   
   # Install dependencies
   pip install -r requirements.txt
   ```

## Connecting to Claude AI Desktop App

### Step 1: Locate Claude Configuration Directory

The configuration file location depends on your operating system:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### Step 2: Update Claude Configuration

1. **Find or create the configuration file** at the location above
2. **Add the MCP server configuration:**

```json
{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "/Users/Projects/MCP/venv/bin/python",
      "args": ["/Users/Projects/MCP/server.py"],
      "env": {}
    }
  }
}
```

**Important**: Replace `/Users/Projects/MCP/server.py` with the actual absolute path to your `server.py` file.

### Step 3: Restart Claude Desktop App

Close and restart the Claude desktop application completely.

### Step 4: Test the Connection

1. Open Claude desktop app
2. In a new conversation, you should see MCP tools available
3. Try asking Claude to use one of the tools, for example:
   - "Can you calculate 15 * 23 for me?"
   - "Please count the words in this text: 'Hello world this is a test'"
   - "List the files in the current directory"

## Testing the Server Manually

You can test the server directly:

```bash
# Activate virtual environment
source venv/bin/activate

# Run the server (it will wait for input)
python server.py
```

The server communicates via stdio (standard input/output) using JSON-RPC protocol.

## Troubleshooting

### Common Issues:

1. **"Import mcp could not be resolved"**
   - Make sure you've installed the requirements: `pip install -r requirements.txt`
   - Activate your virtual environment: `source venv/bin/activate`

2. **Claude doesn't show MCP tools**
   - Check that the path in `claude_desktop_config.json` is absolute and correct
   - Ensure Claude desktop app was completely restarted
   - Check Claude's logs for any error messages

3. **Server won't start**
   - Ensure Python 3.7+ is installed
   - Check that all dependencies are installed
   - Try running the setup script again

### Configuration Example for Different Setups:

**If using conda environment:**
```json
{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "conda",
      "args": ["run", "-n", "your_env_name", "python", "/full/path/to/server.py"],
      "env": {}
    }
  }
}
```

**If using system Python:**
```json
{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "/usr/bin/python3",
      "args": ["/full/path/to/server.py"],
      "env": {}
    }
  }
}
```

## Extending the Server

To add new tools:

1. Add a new `Tool` definition in the `list_tools()` function
2. Add the corresponding handler in the `call_tool()` function
3. Restart the server and Claude desktop app

## Example Usage in Claude

Once connected, you can ask Claude to:

- "Calculate the square root of 144"
- "Count words in this paragraph: [your text]"
- "Convert this text to uppercase: hello world"
- "Show me what files are in my home directory"
- "What's my system information?"

## File Structure

```
MCP/
├── server.py                    # Main MCP server code
├── requirements.txt             # Python dependencies
├── setup.sh                     # Setup script
├── claude_desktop_config.json   # Example Claude config
├── README.md                    # This file
└── venv/                        # Virtual environment (created by setup)
```

## Security Note

This server includes a basic `calculate` function that uses Python's `eval()`. In a production environment, you should replace this with a safer mathematical expression parser.

## License

This project is provided as-is for educational and development purposes.