chore: Update environment configuration and package dependencies for MCP server
- Change MCP_SERVER in .env.example to use port 7123 - Add USE_STDIO_TRANSPORT flag in .env.example for stdio transport mode - Update bun.lock to include new dependencies: cors, express, ajv, and their type definitions - Add new scripts for building and running the MCP server with stdio transport - Introduce PUBLISHING.md for npm publishing guidelines - Enhance README with detailed setup instructions and tool descriptions
This commit is contained in:
jango-blockchained
452
README.md
452
README.md
@@ -1,3 +1,226 @@
|
||||
# Home Assistant Model Context Protocol (MCP)
|
||||
|
||||
A standardized protocol for AI assistants to interact with Home Assistant, providing a secure, typed, and extensible interface for controlling smart home devices.
|
||||
|
||||
## Overview
|
||||
|
||||
The Model Context Protocol (MCP) server acts as a bridge between AI models (like Claude, GPT, etc.) and Home Assistant, enabling AI assistants to:
|
||||
|
||||
- Execute commands on Home Assistant devices
|
||||
- Retrieve information about the smart home
|
||||
- Stream responses for long-running operations
|
||||
- Validate parameters and inputs
|
||||
- Provide consistent error handling
|
||||
|
||||
## Features
|
||||
|
||||
- **Modular Architecture** - Clean separation between transport, middleware, and tools
|
||||
- **Typed Interface** - Fully TypeScript typed for better developer experience
|
||||
- **Multiple Transports**:
|
||||
- **Standard I/O** (stdin/stdout) for CLI integration
|
||||
- **HTTP/REST API** with Server-Sent Events support for streaming
|
||||
- **Middleware System** - Validation, logging, timeout, and error handling
|
||||
- **Built-in Tools**:
|
||||
- Light control (brightness, color, etc.)
|
||||
- Climate control (thermostats, HVAC)
|
||||
- More to come...
|
||||
- **Extensible Plugin System** - Easily add new tools and capabilities
|
||||
- **Streaming Responses** - Support for long-running operations
|
||||
- **Parameter Validation** - Using Zod schemas
|
||||
- **Claude & Cursor Integration** - Ready-made utilities for AI assistants
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 16+
|
||||
- Home Assistant instance (or you can use the mock implementations for testing)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/your-repo/homeassistant-mcp.git
|
||||
|
||||
# Install dependencies
|
||||
cd homeassistant-mcp
|
||||
npm install
|
||||
|
||||
# Build the project
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Running the Server
|
||||
|
||||
```bash
|
||||
# Start with standard I/O transport (for AI assistant integration)
|
||||
npm start -- --stdio
|
||||
|
||||
# Start with HTTP transport (for API access)
|
||||
npm start -- --http
|
||||
|
||||
# Start with both transports
|
||||
npm start -- --stdio --http
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Configure the server using environment variables or a `.env` file:
|
||||
|
||||
```dotenv
|
||||
# Server configuration
|
||||
PORT=3000
|
||||
NODE_ENV=development
|
||||
|
||||
# Execution settings
|
||||
EXECUTION_TIMEOUT=30000
|
||||
STREAMING_ENABLED=true
|
||||
|
||||
# Transport settings
|
||||
USE_STDIO_TRANSPORT=true
|
||||
USE_HTTP_TRANSPORT=true
|
||||
|
||||
# Debug and logging
|
||||
DEBUG_MODE=false
|
||||
DEBUG_STDIO=false
|
||||
DEBUG_HTTP=false
|
||||
SILENT_STARTUP=false
|
||||
|
||||
# CORS settings
|
||||
CORS_ORIGIN=*
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
The MCP server is built with a layered architecture:
|
||||
|
||||
1. **Transport Layer** - Handles communication protocols (stdio, HTTP)
|
||||
2. **Middleware Layer** - Processes requests through a pipeline
|
||||
3. **Tool Layer** - Implements specific functionality
|
||||
4. **Resource Layer** - Manages stateful resources
|
||||
|
||||
### Tools
|
||||
|
||||
Tools are the primary way to add functionality to the MCP server. Each tool:
|
||||
|
||||
- Has a unique name
|
||||
- Accepts typed parameters
|
||||
- Returns typed results
|
||||
- Can stream partial results
|
||||
- Validates inputs and outputs
|
||||
|
||||
Example tool registration:
|
||||
|
||||
```typescript
|
||||
import { LightsControlTool } from "./tools/homeassistant/lights.tool.js";
|
||||
import { ClimateControlTool } from "./tools/homeassistant/climate.tool.js";
|
||||
|
||||
// Register tools
|
||||
server.registerTool(new LightsControlTool());
|
||||
server.registerTool(new ClimateControlTool());
|
||||
```
|
||||
|
||||
### API
|
||||
|
||||
When running with HTTP transport, the server provides a JSON-RPC 2.0 API:
|
||||
|
||||
- `POST /api/mcp/jsonrpc` - Execute a tool
|
||||
- `GET /api/mcp/stream` - Connect to SSE stream for real-time updates
|
||||
- `GET /api/mcp/info` - Get server information
|
||||
- `GET /health` - Health check endpoint
|
||||
|
||||
## Integration with AI Models
|
||||
|
||||
### Claude Integration
|
||||
|
||||
```typescript
|
||||
import { createClaudeToolDefinitions } from "./mcp/index.js";
|
||||
|
||||
// Generate Claude-compatible tool definitions
|
||||
const claudeTools = createClaudeToolDefinitions([
|
||||
new LightsControlTool(),
|
||||
new ClimateControlTool()
|
||||
]);
|
||||
|
||||
// Use with Claude API
|
||||
const messages = [
|
||||
{ role: "user", content: "Turn on the lights in the living room" }
|
||||
];
|
||||
|
||||
const response = await claude.messages.create({
|
||||
model: "claude-3-opus-20240229",
|
||||
messages,
|
||||
tools: claudeTools
|
||||
});
|
||||
```
|
||||
|
||||
### Cursor Integration
|
||||
|
||||
To use the Home Assistant MCP server with Cursor, add the following to your `.cursor/config/config.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"homeassistant-mcp": {
|
||||
"command": "bash",
|
||||
"args": ["-c", "cd ${workspaceRoot} && bun run dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"],
|
||||
"env": {
|
||||
"NODE_ENV": "development",
|
||||
"USE_STDIO_TRANSPORT": "true",
|
||||
"DEBUG_STDIO": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This configuration:
|
||||
1. Runs the MCP server with stdio transport
|
||||
2. Redirects all stderr output to /dev/null
|
||||
3. Uses grep to filter stdout for lines containing `{"jsonrpc":"2.0"`, ensuring clean JSON-RPC output
|
||||
|
||||
#### Troubleshooting Cursor Integration
|
||||
|
||||
If you encounter a "failed to create client" error when using the MCP server with Cursor:
|
||||
|
||||
1. Make sure you're using the correct command and arguments in your Cursor configuration
|
||||
- The bash script approach ensures only valid JSON-RPC messages reach Cursor
|
||||
- Ensure the server is built by running `bun run build` before trying to connect
|
||||
|
||||
2. Ensure the server is properly outputting JSON-RPC messages to stdout:
|
||||
```bash
|
||||
bun run dist/index.js --stdio 2>/dev/null | grep -E '\{"jsonrpc":"2\.0"' > json_only.txt
|
||||
```
|
||||
Then examine json_only.txt to verify it contains only valid JSON-RPC messages.
|
||||
|
||||
3. Make sure grep is installed on your system (it should be available by default on most systems)
|
||||
|
||||
4. Try rebuilding the server with:
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
|
||||
5. Enable debug mode by setting `DEBUG_STDIO=true` in the environment variables
|
||||
|
||||
If the issue persists, you can try:
|
||||
1. Restarting Cursor
|
||||
2. Clearing Cursor's cache (Help > Developer > Clear Cache and Reload)
|
||||
3. Using a similar approach with Node.js:
|
||||
```json
|
||||
{
|
||||
"command": "bash",
|
||||
"args": ["-c", "cd ${workspaceRoot} && node dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"]
|
||||
}
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
|
||||
# MCP Server for Home Assistant 🏠🤖
|
||||
|
||||
[](LICENSE) [](https://bun.sh) [](https://www.typescriptlang.org) [](https://smithery.ai/server/@jango-blockchained/advanced-homeassistant-mcp)
|
||||
@@ -12,6 +235,7 @@ MCP (Model Context Protocol) Server is my lightweight integration tool for Home
|
||||
- 📡 WebSocket/Server-Sent Events (SSE) for state updates
|
||||
- 🤖 Simple automation rule management
|
||||
- 🔐 JWT-based authentication
|
||||
- 🔄 Standard I/O (stdio) transport for integration with Claude and other AI assistants
|
||||
|
||||
## Why Bun? 🚀
|
||||
|
||||
@@ -201,11 +425,12 @@ Add to `.cursor/config/config.json`:
|
||||
{
|
||||
"mcpServers": {
|
||||
"homeassistant-mcp": {
|
||||
"command": "bun",
|
||||
"args": ["run", "start"],
|
||||
"cwd": "${workspaceRoot}",
|
||||
"command": "bash",
|
||||
"args": ["-c", "cd ${workspaceRoot} && bun run dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"],
|
||||
"env": {
|
||||
"NODE_ENV": "development"
|
||||
"NODE_ENV": "development",
|
||||
"USE_STDIO_TRANSPORT": "true",
|
||||
"DEBUG_STDIO": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -317,3 +542,222 @@ MIT License. See [LICENSE](LICENSE) for details.
|
||||
## Author 👨💻
|
||||
|
||||
Created by [jango-blockchained](https://github.com/jango-blockchained)
|
||||
|
||||
## Running with Standard I/O Transport 📝
|
||||
|
||||
MCP Server supports a JSON-RPC 2.0 stdio transport mode for direct integration with AI assistants like Claude:
|
||||
|
||||
### MCP Stdio Features
|
||||
|
||||
✅ **JSON-RPC 2.0 Compatibility**: Full support for the MCP protocol standard
|
||||
✅ **NPX Support**: Run directly without installation using `npx homeassistant-mcp`
|
||||
✅ **Auto Configuration**: Creates necessary directories and default configuration
|
||||
✅ **Cross-Platform**: Works on macOS, Linux, and Windows
|
||||
✅ **Claude Desktop Integration**: Ready to use with Claude Desktop
|
||||
✅ **Parameter Validation**: Automatic validation of tool parameters
|
||||
✅ **Error Handling**: Standardized error codes and handling
|
||||
✅ **Detailed Logging**: Logs to files without polluting stdio
|
||||
|
||||
### Option 1: Using NPX (Easiest)
|
||||
|
||||
Run the MCP server directly without installation using npx:
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
npx homeassistant-mcp
|
||||
|
||||
# Or with environment variables
|
||||
HASS_URL=http://your-ha-instance:8123 HASS_TOKEN=your_token npx homeassistant-mcp
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Install the package temporarily
|
||||
2. Automatically run in stdio mode with JSON-RPC 2.0 transport
|
||||
3. Create a logs directory for logging
|
||||
4. Create a default .env file if not present
|
||||
|
||||
Perfect for integration with Claude Desktop or other MCP clients.
|
||||
|
||||
#### Integrating with Claude Desktop
|
||||
|
||||
To use MCP with Claude Desktop:
|
||||
|
||||
1. Open Claude Desktop settings
|
||||
2. Go to the "Advanced" tab
|
||||
3. Under "MCP Server", select "Custom"
|
||||
4. Enter the command: `npx homeassistant-mcp`
|
||||
5. Click "Save"
|
||||
|
||||
Claude will now use the MCP server for Home Assistant integration, allowing you to control your smart home directly through Claude.
|
||||
|
||||
### Option 2: Local Installation
|
||||
|
||||
1. Update your `.env` file to enable stdio transport:
|
||||
```
|
||||
USE_STDIO_TRANSPORT=true
|
||||
```
|
||||
|
||||
2. Run the server using the stdio-start script:
|
||||
```bash
|
||||
./stdio-start.sh
|
||||
```
|
||||
|
||||
Available options:
|
||||
```
|
||||
./stdio-start.sh --debug # Enable debug mode
|
||||
./stdio-start.sh --rebuild # Force rebuild
|
||||
./stdio-start.sh --help # Show help
|
||||
```
|
||||
|
||||
When running in stdio mode:
|
||||
- The server communicates via stdin/stdout using JSON-RPC 2.0 format
|
||||
- No HTTP server is started
|
||||
- Console logging is disabled to avoid polluting the stdio stream
|
||||
- All logs are written to the log files in the `logs/` directory
|
||||
|
||||
### JSON-RPC 2.0 Message Format
|
||||
|
||||
#### Request Format
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "unique-request-id",
|
||||
"method": "tool-name",
|
||||
"params": {
|
||||
"param1": "value1",
|
||||
"param2": "value2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Format
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "unique-request-id",
|
||||
"result": {
|
||||
// Tool-specific result data
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Error Response Format
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "unique-request-id",
|
||||
"error": {
|
||||
"code": -32000,
|
||||
"message": "Error message",
|
||||
"data": {} // Optional error details
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Notification Format (Server to Client)
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "notification-type",
|
||||
"params": {
|
||||
// Notification data
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Supported Error Codes
|
||||
|
||||
| Code | Description | Meaning |
|
||||
|---------|--------------------|------------------------------------------|
|
||||
| -32700 | Parse error | Invalid JSON was received |
|
||||
| -32600 | Invalid request | JSON is not a valid request object |
|
||||
| -32601 | Method not found | Method does not exist or is unavailable |
|
||||
| -32602 | Invalid params | Invalid method parameters |
|
||||
| -32603 | Internal error | Internal JSON-RPC error |
|
||||
| -32000 | Tool execution | Error executing the tool |
|
||||
| -32001 | Validation error | Parameter validation failed |
|
||||
|
||||
### Integrating with Claude Desktop
|
||||
|
||||
To use this MCP server with Claude Desktop:
|
||||
|
||||
1. Create or edit your Claude Desktop configuration:
|
||||
```bash
|
||||
# On macOS
|
||||
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
||||
|
||||
# On Linux
|
||||
nano ~/.config/Claude/claude_desktop_config.json
|
||||
|
||||
# On Windows
|
||||
notepad %APPDATA%\Claude\claude_desktop_config.json
|
||||
```
|
||||
|
||||
2. Add the MCP server configuration:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"homeassistant-mcp": {
|
||||
"command": "npx",
|
||||
"args": ["homeassistant-mcp"],
|
||||
"env": {
|
||||
"HASS_TOKEN": "your_home_assistant_token_here",
|
||||
"HASS_HOST": "http://your_home_assistant_host:8123"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Restart Claude Desktop.
|
||||
|
||||
4. In Claude, you can now use the Home Assistant MCP tools.
|
||||
|
||||
### JSON-RPC 2.0 Message Format
|
||||
|
||||
## Usage
|
||||
|
||||
### Using NPX (Easiest)
|
||||
|
||||
The simplest way to use the Home Assistant MCP server is through NPX:
|
||||
|
||||
```bash
|
||||
# Start the server in stdio mode
|
||||
npx homeassistant-mcp
|
||||
```
|
||||
|
||||
This will automatically:
|
||||
1. Start the server in stdio mode
|
||||
2. Output JSON-RPC messages to stdout
|
||||
3. Send log messages to stderr
|
||||
4. Create a logs directory if it doesn't exist
|
||||
|
||||
You can redirect stderr to hide logs and only see the JSON-RPC output:
|
||||
|
||||
```bash
|
||||
npx homeassistant-mcp 2>/dev/null
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
If you prefer to install the package globally or locally:
|
||||
|
||||
```bash
|
||||
# Install globally
|
||||
npm install -g homeassistant-mcp
|
||||
|
||||
# Then run
|
||||
homeassistant-mcp
|
||||
```
|
||||
|
||||
Or install locally:
|
||||
|
||||
```bash
|
||||
# Install locally
|
||||
npm install homeassistant-mcp
|
||||
|
||||
# Then run using npx
|
||||
npx homeassistant-mcp
|
||||
```
|
||||
|
||||
### Advanced Usage
|
||||
|
||||
Reference in New Issue
Block a user