Content
# Simple MCP Character Counter
A minimal Model Context Protocol (MCP) server for teaching purposes. This server provides a single tool that counts the number of characters in a word or phrase.
## What is MCP?
Model Context Protocol (MCP) is a standardized way for AI assistants (like Claude) to interact with external tools and data sources. This simple example demonstrates the core concepts of building an MCP server.
## Features
This teaching example includes:
- **One simple tool**: `count_characters` - counts characters in text
- **Clear documentation**: Every function and concept is explained
- **Minimal dependencies**: Only requires the MCP Python SDK
## Setup
### 1. Install Dependencies
```bash
python3 -m venv venv
source venv/bin/activate
```
Or install directly:
```bash
python -m pip install -r requirements.txt
```
### 2. Test the Server
You can run the server directly to make sure it works:
```bash
python server.py
```
The server will start and wait for input via stdin. You can press `Ctrl+C` to stop it.
## Usage with Claude Desktop
To use this MCP server with Claude Desktop, you need to add it to Claude's configuration file.
```bash
python server.py
```
The server will start and wait for input via stdin. You can press `Ctrl+C` to stop it.
## Usage with Claude Desktop
To use this MCP server with Claude Desktop, you need to add it to Claude's configuration file.
### Quick Configuration
A ready-to-use configuration file is included: `claude_desktop_config.json`
**Option 1: Copy the entire config (if you have no other MCP servers)**
```bash
# MacOS
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Windows (PowerShell)
Copy-Item claude_desktop_config.json $env:APPDATA\Claude\claude_desktop_config.json
```
**Option 2: Merge with existing config (if you have other MCP servers)**
1. Open your Claude Desktop configuration file:
- **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
2. Add the `simple-character-counter` entry to your existing `mcpServers` section:
```json
{
"mcpServers": {
"simple-character-counter": {
"command": "python",
"args": ["/Users/electron/workspace/Nanocentury AI/NIO-MCPs/supersimpleMCP/server.py"]
}
}
}
```
**Note**: Update the path in `args` if you move this folder to a different location.
3. Restart Claude Desktop
4. The tool will now be available! You can ask Claude to:
- "Count the characters in 'hello'"
- "How many characters are in 'MCP is awesome'?"
- "Use the character counter on this text: ..."
## How It Works
### Server Structure
The server has three main parts:
1. **Server Instance** (`app = Server(...)`): Creates the MCP server
2. **Tool Definition** (`@app.list_tools()`): Describes what tools are available
3. **Tool Handler** (`@app.call_tool()`): Executes tools when called
### The Character Counter Tool
When you ask Claude to count characters:
1. Claude sees the `count_characters` tool is available
2. Claude calls the tool with your text
3. The server counts the characters using `len(text)`
4. The server returns a formatted response
5. Claude shares the result with you
## Code Walkthrough
### Key Components
```python
# Create the server
app = Server("simple-character-counter")
# Define available tools
@app.list_tools()
async def list_tools() -> list[Tool]:
return [Tool(...)]
# Handle tool execution
@app.call_tool()
async def call_tool(name: str, arguments: Any) -> list[TextContent]:
# Your tool logic here
pass
# Start the server
async def main():
async with stdio_server() as (read_stream, write_stream):
await app.run(read_stream, write_stream, ...)
```
## Learning Points
This example teaches:
1. **MCP Server Basics**: How to create and run an MCP server
2. **Tool Definition**: How to define a tool with name, description, and input schema
3. **Tool Execution**: How to handle tool calls and return results
4. **JSON Schema**: How to specify input parameters for tools
5. **Async Python**: Basic async/await patterns used in MCP
## Extending This Example
Try modifying this server to practice:
- Add a new tool (e.g., `count_words`, `reverse_text`)
- Add more parameters to the existing tool
- Return different formats of output
- Add error handling for edge cases
## Troubleshooting
**Server won't start in Claude Desktop:**
- Check that the full path to `server.py` is correct
- Make sure you've installed the requirements
- Restart Claude Desktop after config changes
**Tool doesn't appear:**
- Verify the JSON configuration is valid (no syntax errors)
- Check Claude's developer logs for error messages
## Resources
- [MCP Documentation](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
## License
This is a teaching example - feel free to use and modify as needed!
