Setup Guide¶

Quick Setup¶

Navigate to the project directory:
```
cd projects/week3/perception-tools
```
Install dependencies:
```
pip install -r requirements.txt
```

Configure environment variables:

cp env.example .env
# Edit .env with your API keys

Test the installation:
```
python test_imports.py
```
Run the quickstart demo:
```
python quickstart.py
```
Start the MCP server:
```
python src/main.py
```

Detailed API Setup¶

Google Custom Search (Required for web search)¶

Go to Google Cloud Console
Create a new project
Enable "Custom Search API"
Create an API key in "Credentials"
Go to Programmable Search Engine
Create a new search engine
Configure it to search the entire web
Get your Search Engine ID (cx parameter)

Add to .env:

GOOGLE_API_KEY=your_api_key
GOOGLE_CSE_ID=your_search_engine_id

OpenWeather API (Required for weather)¶

Sign up at OpenWeatherMap
Get your API key from the dashboard
Add to .env:
```
OPENWEATHER_API_KEY=your_api_key
```

Notion API (Optional)¶

Go to Notion Integrations
Create a new integration
Copy the "Internal Integration Token"
Share your databases/pages with the integration
Install the Notion SDK:
```
pip install notion-client
```
Add to .env:
```
NOTION_API_KEY=your_integration_token
```

Google Calendar API (Optional)¶

Go to Google Cloud Console
Enable "Google Calendar API"
Create OAuth 2.0 credentials
Download the credentials JSON file

Install required packages:

pip install google-auth-oauthlib google-auth-httplib2 google-api-python-client

Run the OAuth flow (first time only):

# This will open a browser for authentication
# The token will be saved to ~/.perception-tools/google_token.pickle

Using with MCP Clients¶

Claude Desktop Configuration¶

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server configuration:

{
  "mcpServers": {
    "perception-tools": {
      "command": "python",
      "args": ["/absolute/path/to/perception-tools/src/main.py"],
      "env": {
        "GOOGLE_API_KEY": "your_key",
        "GOOGLE_CSE_ID": "your_cse_id",
        "OPENWEATHER_API_KEY": "your_key"
      }
    }
  }
}

Other MCP Clients¶

The server uses stdio transport and can be integrated with any MCP-compatible client. Refer to your client's documentation for configuration details.

Troubleshooting¶

Import Errors¶

If you see import errors, make sure all dependencies are installed:

pip install -r requirements.txt

API Errors¶

If API calls fail: 1. Check that your API keys are correctly set in .env 2. Verify your API quotas haven't been exceeded 3. Check the API service status

File Permission Errors¶

Ensure the script has write permissions for: - Download directory (for file downloads) - ~/.perception-tools/ (for OAuth tokens)

Module Not Found¶

If Python can't find modules, ensure you're running from the correct directory or adjust your PYTHONPATH:

export PYTHONPATH="${PYTHONPATH}:/path/to/perception-tools/src"

Development¶

Running Tests¶

# Test imports
python test_imports.py

# Test tools
python quickstart.py

Adding New Tools¶

Choose the appropriate module (or create a new one)

Implement the tool function following the pattern:

async def my_tool(param: str) -> Union[str, TextContent]:
    try:
        # Implementation
        return TextContent(...)
    except Exception as e:
        # Error handling
        return TextContent(...)

Register the tool in main.py using @mcp.tool decorator
Update documentation

Code Style¶

Follow KISS, DRY, and SOLID principles
Use type hints
Include docstrings for all functions
Return standardized ActionResponse format
Include comprehensive error handling

Support¶

For issues and questions: 1. Check this setup guide 2. Review the main README.md 3. Check tool-specific documentation 4. Review API provider documentation