README.md•3.9 kB
# Simple MCP Server
A simple Model Context Protocol (MCP) server that provides value lookup operations. This server implements a basic key-value store that can be accessed by MCP-compatible AI assistants and clients.
## Features
- **In-memory key-value store**: Store and retrieve data during the session
- **JSON support**: Automatically parses and formats JSON values
- **Multiple operations**: Get, set, delete, list, and clear operations
- **MCP protocol compliance**: Uses the standard MCP protocol for communication
- **Easy integration**: Can be used with any MCP-compatible client
## Available Tools
The server provides the following tools that can be called by MCP clients:
### `get_value`
Retrieve a value from the store by key.
- **Parameters**: `key` (string) - The key to look up
- **Returns**: The value associated with the key, or an error message if not found
### `set_value`
Store a key-value pair in the store.
- **Parameters**:
- `key` (string) - The key to store
- `value` (string) - The value to store (automatically parsed as JSON if valid)
- **Returns**: Confirmation message
### `delete_value`
Remove a key-value pair from the store.
- **Parameters**: `key` (string) - The key to delete
- **Returns**: Confirmation message
### `list_keys`
List all keys currently in the store.
- **Parameters**: None
- **Returns**: A formatted list of all keys
### `clear_values`
Clear all key-value pairs from the store.
- **Parameters**: None
- **Returns**: Confirmation message
### `get_store_info`
Get information about the current state of the store.
- **Parameters**: None
- **Returns**: Store statistics and sample keys
## Installation
1. Clone this repository:
```bash
git clone https://github.com/jmgress/simple-mcp.git
cd simple-mcp
```
2. Install dependencies:
```bash
pip install -e .
```
## Usage
### Running the Server
Start the MCP server using stdio transport:
```bash
simple-mcp-server
```
Or run directly with Python:
```bash
python -m simple_mcp.server
```
### Testing the Server
You can test the server functionality using the included test script:
```bash
python test_server.py
```
This will demonstrate all available operations and show you how the server responds.
### Using with MCP Clients
The server can be used with any MCP-compatible client. Configure your client to connect to this server using stdio transport.
Example client configuration (varies by client):
```json
{
"servers": {
"simple-mcp": {
"command": "simple-mcp-server",
"transport": "stdio"
}
}
}
```
## Example Operations
Here are some example operations you can perform:
```python
# Store a simple string value
set_value(key="greeting", value="Hello, World!")
# Store JSON data
set_value(key="user", value='{"name": "Alice", "age": 30}')
# Retrieve values
get_value(key="greeting") # Returns: "Hello, World!"
get_value(key="user") # Returns formatted JSON
# List all keys
list_keys() # Returns: "Keys in store (2 total): greeting, user"
# Get store information
get_store_info() # Returns current store statistics
# Clean up
delete_value(key="greeting")
clear_values() # Removes all data
```
## Architecture
The server is built using:
- **FastMCP**: A high-level MCP server framework
- **JSON-RPC 2.0**: For client-server communication
- **Pydantic**: For data validation and serialization
- **asyncio**: For asynchronous operation
The value store is currently in-memory only, meaning data is lost when the server restarts. This makes it suitable for temporary storage and demonstration purposes.
## Development
To set up for development:
```bash
# Install in development mode with dev dependencies
pip install -e ".[dev]"
# Run tests
python test_server.py
# Format code
black src/
# Lint code
ruff check src/
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
.