google-home-api-agent by timhuang1018 - MCP Server

Google Home API Agent

A RAG (Retrieval-Augmented Generation) powered agent for querying Google Home Android API documentation.

Overview

This project provides an intelligent agent that can answer questions about the Google Home Android API by:

Crawling official documentation from developers.home.google.com
Processing and chunking documentation into semantic sections
Building a hybrid search index (vector embeddings + BM25)
Using LLMs to provide accurate, context-aware answers
NEW: MCP server with context-aware output modes (question vs integration)

Project Structure

google-home-api-agent/
├── data/
│   └── home-api/
│       └── android/
│           ├── *.md                    # Raw crawled markdown files
│           ├── processed/              # Processed chunks and metadata
│           │   ├── chunks.jsonl
│           │   ├── code_examples.jsonl
│           │   └── metadata.json
│           └── index/                  # Search indices
│               ├── chroma/             # Vector embeddings
│               ├── bm25_index.pkl      # Keyword search index
│               └── chunk_mapping.json  # Chunk ID mappings
├── scripts/
│   ├── google-home-android-api.py     # Documentation crawler
│   ├── process_docs.py                # Document processor
│   └── build_index.py                 # Index builder
├── google_home_rag/
│   ├── __init__.py
│   ├── agent.py                       # RAG agent implementation
│   └── retriever.py                   # Hybrid retriever
├── tests/
│   └── rag_tests/
│       ├── evaluation_framework.py    # Evaluation tools
│       ├── run_evaluation.py          # Test runner
│       └── profile_performance.py     # Performance profiling
├── google_home_mcp_server.py          # MCP server implementation
├── run_mcp_server.py                  # MCP server startup script
├── MCP_SERVER.md                      # MCP server documentation
├── pyproject.toml
├── .env.example
└── README.md

Setup

1. Prerequisites

Python 3.10 or higher
uv (recommended) or pip

2. Installation

Using uv (recommended):

cd /Users/tim/PycharmProjects/google-home-api-agent

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Using pip:

cd /Users/tim/PycharmProjects/google-home-api-agent

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

3. Configuration

Copy the example environment file and add your API keys:

cp .env.example .env

Edit .env and add your OpenAI API key:

OPENAI_API_KEY=your-actual-api-key-here

Usage

MCP Server (Recommended for AI Assistants)

NEW: Use the MCP server for seamless integration with Claude Desktop, Cline, and other MCP clients:

# Start the MCP server
python run_mcp_server.py

The MCP server provides:

ask_question - Get lean code snippets without imports (for learning)
get_code_integration - Get complete code with imports (for implementation)
search_documentation - Browse documentation sections

📖

Crawling Documentation

To update or re-crawl the documentation:

python scripts/google-home-android-api.py

This will:

Crawl all configured pages from developers.home.google.com
Save markdown files to data/home-api/android/

Processing Documents

Process the raw markdown into structured chunks:

python scripts/process_docs.py

This will:

Parse markdown files
Extract code blocks and metadata
Chunk documents by sections
Save processed data to data/home-api/android/processed/

Building the Index

Build the hybrid search index:

python scripts/build_index.py

This will:

Create vector embeddings using ChromaDB
Build BM25 keyword index
Save indices to data/home-api/android/index/

Using the RAG Agent

from pathlib import Path
from google_home_rag import RAGAgent

# Initialize the agent
index_dir = Path("data/home-api/android/index")
agent = RAGAgent(index_dir=index_dir, model="gpt-4o-mini")

# Ask a question
question = "How do I commission a device using the Android API?"
answer = agent.answer(question, top_k=5)

print(answer)

Running Evaluations

To evaluate the RAG system performance:

cd tests/rag_tests
python run_evaluation.py

Performance Profiling

To profile the RAG system:

cd tests/rag_tests
python profile_performance.py

Documentation Coverage

The agent currently covers:

Get Started

SDK setup and OAuth
Initialization and permissions

API Guides

Overview and data model
Connectivity and interoperability
Error handling

Commissioning API

Device commissioning
Multi-admin support

Structure API

Home structure management

Device API

Device control and monitoring
Supported device types and traits
Manufacturer-specific traits

Automation API

Automation design and building
DSL (Domain Specific Language)
- Basic patterns
- Complex patterns
- Recurring starters
Supported traits and simplified traits
Blocked actions
Discovery and examples

Testing

Test guidelines

Development

Adding New Documentation Pages

Edit scripts/google-home-android-api.py and add URLs to the PAGES_TO_CRAWL list:

PAGES_TO_CRAWL = [
    "/apis/android/your-new-page",
    # ...
]

Then re-run the crawler, processor, and index builder.

Customizing the RAG Agent

The RAG agent can be customized in google_home_rag/agent.py:

Adjust retrieval parameters (top_k, reranking)
Modify prompt templates
Change LLM models
Add custom filters

Testing

Add test cases to tests/rag_tests/test_cases/:

[
  {
    "question": "Your question here",
    "expected_keywords": ["keyword1", "keyword2"],
    "category": "category_name"
  }
]

Dependencies

Core dependencies:

crawl4ai: Web crawling and content extraction
chromadb: Vector database for embeddings
sentence-transformers: Embedding generation
rank-bm25: Keyword-based search
openai: LLM interface
litellm: Multi-provider LLM support

Troubleshooting

ChromaDB Issues

If you encounter ChromaDB errors:

# Clear the index and rebuild
rm -rf data/home-api/android/index/chroma
python scripts/build_index.py

Import Errors

Make sure the project is installed in editable mode:

uv pip install -e .
# or
pip install -e .

API Key Issues

Verify your .env file is in the project root and contains:

OPENAI_API_KEY=sk-...

License

This project is for educational and research purposes. Please refer to Google's terms of service for their API documentation.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Support

For issues or questions, please open an issue on the project repository.