gchat-mcp 0.1.0__tar.gz

gchat_mcp-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Sensitive files
+credentials.json
+token.json
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+env/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+.env
+.env.local
+
+.pytest_cache

gchat_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,60 @@
+# gchat-mcp Agent Guide
+
+## Setup & Environment
+
+### Installation (using uv)
+```bash
+uv venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+```
+
+### OAuth Flow (required first run)
+```bash
+uv run python -c "from src.apps.gchat_mcp.server import get_chat_client; client = get_chat_client()"
+```
+This generates `token.json` in project root.
+
+## Commands
+
+### Run server
+```bash
+uv run python -m src.apps.gchat_mcp.server
+# or
+uv run gchat-mcp
+```
+
+### Run tests
+```bash
+uv run pytest
+```
+
+### Code quality
+```bash
+uv run ruff check src/
+uv run ruff format src/ --check
+```
+
+## Architecture
+
+- **Package**: `gchat-mcp` (FastMCP-based MCP server)
+- **Entrypoint**: `src/apps/gchat_mcp/server.py`
+- **Tools**: `list_spaces()`, `list_messages(space_id, limit=20)`, `search_messages(space_id, query)`
+- **Auth**: OAuth2 via `credentials.json` (service account) + `token.json` (user tokens)
+
+## Critical Constraints
+
+### Never commit secrets
+- `.gitignore` excludes: `credentials.json`, `token.json`, `.env*`
+- These files contain sensitive Google Cloud credentials
+
+### Token storage location
+OAuth tokens are saved to `token.json` in project root (not inside `src/`)
+
+### Test imports
+Tests add `src` to path via `sys.path.insert(0, str(Path(__file__).parent.parent))`
+
+## Testing Notes
+
+- Tests verify module structure and tool registration, not actual Google Chat API calls
+- No fixtures or external service prerequisites for unit tests
+- Test suite is small (~5 tests in `tests/test_server.py`)

gchat_mcp-0.1.0/MCP_SETUP.md

@@ -0,0 +1,227 @@
+# GChat MCP Server Setup Guide
+
+This guide shows you how to run the GChat MCP server in WSL and connect it to LM Studio on Windows.
+
+## Prerequisites
+
+- WSL (Ubuntu) installed on Windows
+- Python environment with `uv` package manager
+- LM Studio installed on Windows
+
+## Project Structure
+
+```
+ai-meetup-demo/
+├── src/
+│   └── apps/gchat_mcp/
+│       └── server.py      # MCP server implementation
+├── oauth_setup.py         # OAuth setup script
+├── credentials.json       # Google Cloud credentials (already exists)
+└── Makefile               # Project make targets
+```
+
+## Step 1: Install Dependencies
+
+```bash
+make install
+```
+
+This installs all development dependencies using `uv`.
+
+## Step 2: Set Up OAuth Credentials
+
+Run the OAuth flow to generate credentials:
+
+```bash
+make oauth
+```
+
+Or manually:
+
+```bash
+uv run python oauth_setup.py credentials.json
+```
+
+This creates `credentials.json` with Google Cloud service account credentials.
+
+## Step 3: Create MCP Token
+
+Generate the OAuth token for the MCP server:
+
+```bash
+make create-token
+```
+
+Or manually:
+
+```bash
+uv run python -c "from src.apps.gchat_mcp.server import get_chat_client; client = get_chat_client()"
+```
+
+This creates `token.json` in your project root. **Never commit this file.**
+
+## Step 4: Run the MCP Server (WSL)
+
+Start the server in WSL:
+
+```bash
+make run-server
+```
+
+Or manually:
+
+```bash
+uv run python -m src.apps.gchat_mcp.server
+```
+
+The server will start on `http://localhost:2390` by default.
+
+## Step 5: Configure LM Studio (Windows)
+
+Create or edit the MCP config file at:
+
+```
+%APPDATA%\lm-studio\mcp.json
+```
+
+### Option A: Using WSL Command (Python Direct)
+
+```json
+{
+  "mcpServers": {
+    "gchat-mcp": {
+      "command": "wsl",
+      "args": [
+        "-d", "Ubuntu",
+        "-e", "python",
+        "-m", "src.apps.gchat_mcp.server"
+      ]
+    }
+  }
+}
+```
+
+### Option B: Using Full Path (Recommended)
+
+```json
+{
+  "mcpServers": {
+    "gchat-mcp": {
+      "command": "wsl",
+      "args": [
+        "-d", "Ubuntu",
+        "-e", "cd",
+        "-e", "/home/leins275/Projects/its/ai-meetup-demo",
+        "-e", "python",
+        "-m", "src.apps.gchat_mcp.server"
+      ]
+    }
+  }
+}
+```
+
+### Option C: HTTP Transport (Alternative)
+
+If you prefer HTTP transport instead of stdio:
+
+```json
+{
+  "mcpServers": {
+    "gchat-mcp": {
+      "command": "wsl",
+      "args": [
+        "-d", "Ubuntu",
+        "-e", "python",
+        "-m", "fastmcp",
+        "-m", "src.apps.gchat_mcp.server",
+        "--transport=http",
+        "--host=0.0.0.0",
+        "--port=2390"
+      ]
+    }
+  }
+}
+```
+
+## Step 6: Connect LM Studio to MCP Server
+
+1. Open LM Studio on Windows
+2. Go to **Settings** → **MCP Servers**
+3. Add a new server named `gchat-mcp`
+4. Paste the config from Step 5
+5. Click **Save** and **Restart** LM Studio
+
+## Available Make Targets
+
+| Target | Command | Description |
+|--------|---------|-------------|
+| `install` | `make install` | Install dependencies |
+| `setup` | `make setup` | Full setup (install + oauth) |
+| `oauth` | `make oauth` | Run OAuth flow |
+| `create-token` | `make create-token` | Generate MCP token |
+| `run-server` | `make run-server` | Start MCP server |
+| `run-server-cli` | `make run-server-cli` | Start server with CLI |
+| `run-tests` | `make run-tests` | Run pytest tests |
+| `lint` | `make lint` | Run ruff linter |
+| `format` | `make format` | Check code formatting |
+
+## Troubleshooting
+
+### Server won't start in WSL
+
+1. Ensure you're in the project directory:
+   ```bash
+   cd /home/leins275/Projects/its/ai-meetup-demo
+   ```
+
+2. Activate virtual environment:
+   ```bash
+   source .venv/bin/activate
+   ```
+
+3. Reinstall dependencies:
+   ```bash
+   make install
+   ```
+
+### LM Studio can't connect
+
+1. Check that the server is running in WSL:
+   ```bash
+   wsl python -m src.apps.gchat_mcp.server &
+   ```
+
+2. Verify port 2390 is listening:
+   ```bash
+   netstat -tlnp | grep 2390
+   ```
+
+3. Check LM Studio logs for connection errors
+
+### OAuth token issues
+
+1. Delete existing token and recreate:
+   ```bash
+   rm token.json
+   make create-token
+   ```
+
+2. Ensure `credentials.json` exists and is valid
+
+## Security Notes
+
+- **Never commit** `token.json`, `credentials.json`, or `.env*` files
+- These files are excluded in `.gitignore`
+- Keep your Google Cloud credentials secure
+
+## Architecture Overview
+
+```
+Windows (LM Studio)
+    ↓ [wsl command]
+WSL (Ubuntu)
+    ↓ [Python MCP Server]
+Google Chat API
+```
+
+The `wsl` command bridges Windows and WSL, allowing LM Studio to communicate with the Python server running in Ubuntu.

gchat_mcp-0.1.0/Makefile

@@ -0,0 +1,27 @@
+.PHONY: install setup run-server run-tests lint format oauth
+
+install:
+	uv pip install -e ".[dev]"
+
+setup: install oauth
+
+run-server:
+	uv run fastmcp run src/apps/gchat_mcp/server.py --transport http --host 0.0.0.0 --port 2390 &
+
+run-server-cli:
+	uv run gchat-mcp
+
+oauth:
+	uv run python oauth_setup.py credentials.json
+
+create-token:
+	uv run python -c "from src.apps.gchat_mcp.server import get_chat_client; client = get_chat_client()"
+
+run-tests:
+	uv run pytest
+
+lint:
+	uv run ruff check src/
+
+format:
+	uv run ruff format src/ --check

gchat_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: gchat-mcp
+Version: 0.1.0
+Summary: MCP server for Google Chat integration
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Keywords: chatbot,google-chat,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=1.0.0
+Requires-Dist: google-apps-chat>=0.10.0
+Requires-Dist: google-auth>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gchat-mcp
+
+MCP (Model Context Protocol) server for Google Chat integration. This server provides tools to interact with Google Chat spaces and messages.
+
+## Features
+
+- List all Google Chat spaces you're a member of
+- Retrieve recent messages from any space
+- Search messages by text content
+
+## Installation
+
+### Using uv
+
+```bash
+# Create virtual environment
+uv venv
+
+# Activate it
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+uv pip install -e ".[dev]"
+```
+
+### Or with pip
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Setup
+
+1. **Create a Google Cloud project**: [https://console.cloud.google.com/](https://console.cloud.google.com/)
+
+2. **Enable Google Chat API**: 
+    ```bash
+    gcloud services enable chat.googleapis.com
+    ```
+
+3. **Create a service account**:
+    - Go to IAM & Admin > Service Accounts
+    - Click "Create Service Account"
+    - Give it a name (e.g., "gchat-mcp")
+    - Click "Generate Key" and select JSON format
+    - Download the JSON file
+
+4. **Place credentials**: Put your service account JSON as `credentials.json` in the project root
+
+5. **Validate credentials**:
+    ```bash
+    make oauth
+    # or
+    uv run python oauth_setup.py credentials.json
+    ```
+
+## Usage
+
+### As an MCP Server
+
+```bash
+# Start the MCP server
+uv run python -m src.apps.gchat_mcp.server
+```
+
+### Available Tools
+
+#### `list_spaces()`
+
+Returns a list of Google Chat spaces the authenticated user is a member of.
+
+**Example:**
+```python
+from src.apps.gchat_mcp.server import app
+
+# In MCP context
+spaces = await app.call_tool("list_spaces")
+print(spaces)
+# [{'spaceId': 'abc123', 'name': 'General', 'iconLink': 'https://...'}]
+```
+
+#### `list_messages(space_id, limit=20)`
+
+Retrieves recent messages from a specific space.
+
+**Arguments:**
+- `space_id` (str): The unique identifier of the space
+- `limit` (int, optional): Maximum number of messages to retrieve (default: 20)
+
+**Example:**
+```python
+messages = await app.call_tool("list_messages", {"space_id": "abc123", "limit": 10})
+print(messages)
+# [{'messageId': 'msg1', 'text': 'Hello!', 'authorName': 'User1', ...}]
+```
+
+#### `search_messages(space_id, query)`
+
+Searches for messages containing specific text in a space.
+
+**Arguments:**
+- `space_id` (str): The unique identifier of the space to search in
+- `query` (str): The text query to search for
+
+**Example:**
+```python
+results = await app.call_tool("search_messages", {"space_id": "abc123", "query": "meeting"})
+print(results)
+# [{'messageId': 'msg1', 'text': 'Meeting at 3pm...', 'authorName': 'User1', ...}]
+```
+
+## Project Structure
+
+```
+ai-meetup-demo/
+├── pyproject.toml
+├── README.md
+├── src/
+│   ├── config/           # Configuration files
+│   │   └── __init__.py
+│   ├── apps/
+│   │   └── gchat_mcp/    # MCP server application
+│   │       ├── __init__.py
+│   │       └── server.py
+│   └── manage.py         # Entry point
+├── credentials.json      # Google Cloud service account (add to .gitignore)
+├── oauth_setup.py        # OAuth setup helper script
+├── examples/
+│   └── example_usage.py  # Usage examples
+└── tests/
+    └── test_server.py    # Unit tests
+```
+
+## Configuration
+
+### Service Account
+
+Place your Google Cloud service account JSON as `credentials.json` in the project root. This file is excluded from git.
+
+## Development
+
+```bash
+# Install dev dependencies
+uv pip install -e ".[dev]"
+
+# Run tests
+uv run pytest
+
+# Check code quality
+uv run ruff check src/
+uv run ruff format src/ --check
+```
+
+## License
+
+MIT

gchat_mcp-0.1.0/README.md

@@ -0,0 +1,156 @@
+# gchat-mcp
+
+MCP (Model Context Protocol) server for Google Chat integration. This server provides tools to interact with Google Chat spaces and messages.
+
+## Features
+
+- List all Google Chat spaces you're a member of
+- Retrieve recent messages from any space
+- Search messages by text content
+
+## Installation
+
+### Using uv
+
+```bash
+# Create virtual environment
+uv venv
+
+# Activate it
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+uv pip install -e ".[dev]"
+```
+
+### Or with pip
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Setup
+
+1. **Create a Google Cloud project**: [https://console.cloud.google.com/](https://console.cloud.google.com/)
+
+2. **Enable Google Chat API**: 
+    ```bash
+    gcloud services enable chat.googleapis.com
+    ```
+
+3. **Create a service account**:
+    - Go to IAM & Admin > Service Accounts
+    - Click "Create Service Account"
+    - Give it a name (e.g., "gchat-mcp")
+    - Click "Generate Key" and select JSON format
+    - Download the JSON file
+
+4. **Place credentials**: Put your service account JSON as `credentials.json` in the project root
+
+5. **Validate credentials**:
+    ```bash
+    make oauth
+    # or
+    uv run python oauth_setup.py credentials.json
+    ```
+
+## Usage
+
+### As an MCP Server
+
+```bash
+# Start the MCP server
+uv run python -m src.apps.gchat_mcp.server
+```
+
+### Available Tools
+
+#### `list_spaces()`
+
+Returns a list of Google Chat spaces the authenticated user is a member of.
+
+**Example:**
+```python
+from src.apps.gchat_mcp.server import app
+
+# In MCP context
+spaces = await app.call_tool("list_spaces")
+print(spaces)
+# [{'spaceId': 'abc123', 'name': 'General', 'iconLink': 'https://...'}]
+```
+
+#### `list_messages(space_id, limit=20)`
+
+Retrieves recent messages from a specific space.
+
+**Arguments:**
+- `space_id` (str): The unique identifier of the space
+- `limit` (int, optional): Maximum number of messages to retrieve (default: 20)
+
+**Example:**
+```python
+messages = await app.call_tool("list_messages", {"space_id": "abc123", "limit": 10})
+print(messages)
+# [{'messageId': 'msg1', 'text': 'Hello!', 'authorName': 'User1', ...}]
+```
+
+#### `search_messages(space_id, query)`
+
+Searches for messages containing specific text in a space.
+
+**Arguments:**
+- `space_id` (str): The unique identifier of the space to search in
+- `query` (str): The text query to search for
+
+**Example:**
+```python
+results = await app.call_tool("search_messages", {"space_id": "abc123", "query": "meeting"})
+print(results)
+# [{'messageId': 'msg1', 'text': 'Meeting at 3pm...', 'authorName': 'User1', ...}]
+```
+
+## Project Structure
+
+```
+ai-meetup-demo/
+├── pyproject.toml
+├── README.md
+├── src/
+│   ├── config/           # Configuration files
+│   │   └── __init__.py
+│   ├── apps/
+│   │   └── gchat_mcp/    # MCP server application
+│   │       ├── __init__.py
+│   │       └── server.py
+│   └── manage.py         # Entry point
+├── credentials.json      # Google Cloud service account (add to .gitignore)
+├── oauth_setup.py        # OAuth setup helper script
+├── examples/
+│   └── example_usage.py  # Usage examples
+└── tests/
+    └── test_server.py    # Unit tests
+```
+
+## Configuration
+
+### Service Account
+
+Place your Google Cloud service account JSON as `credentials.json` in the project root. This file is excluded from git.
+
+## Development
+
+```bash
+# Install dev dependencies
+uv pip install -e ".[dev]"
+
+# Run tests
+uv run pytest
+
+# Check code quality
+uv run ruff check src/
+uv run ruff format src/ --check
+```
+
+## License
+
+MIT

gchat_mcp-0.1.0/TODO.md

@@ -0,0 +1,9 @@
+Create a Python MCP server called `gchat-mcp` with these tools:
+- list_spaces() — returns list of Google Chat spaces the user is member of
+- list_messages(space_id, limit=20) — returns recent messages from a space
+- search_messages(space_id, query) — filters messages by text
+
+Use `uv` tool for python environment management.
+Use `mcp` Python library (FastMCP), google-apps-chat for API access.
+Auth via OAuth2 with token.json / credentials.json.
+Package it as pypi-ready: pyproject.toml, README.md.