Metadata-Version: 2.4
Name: barie-google-forms-mcp
Version: 0.1.2
Summary: Google Forms MCP Server for managing forms and responses via the Model Context Protocol
Project-URL: Homepage, https://barie.ai
Project-URL: Repository, https://github.com/barie-ai/barie-mcps
Project-URL: Issues, https://github.com/barie-ai/barie-mcps/issues
Author-email: Barie <support@barie.ai>
License: MIT
Keywords: google-api,google-forms,llm-tools,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: google-api-python-client<3.0.0,>=2.130.0
Requires-Dist: google-auth-oauthlib<2.0.0,>=1.2.0
Requires-Dist: google-auth<3.0.0,>=2.29.0
Requires-Dist: mcp<2.0.0,>=0.9.0
Requires-Dist: pydantic<3.0.0,>=2.5.0
Requires-Dist: tenacity<10.0.0,>=8.2.0
Provides-Extra: internal
Requires-Dist: python-dotenv>=1.0.0; extra == 'internal'
Description-Content-Type: text/markdown

# Google Forms MCP Server

An MCP server for managing Google Forms and form responses, integrating seamlessly with AI assistants using the Model Context Protocol.

## Features

- **List Forms**: Search and list Google Forms from Drive with optional title filter and pagination.
- **Get Form**: Retrieve metadata, items, and settings for a specific form.
- **Create Form**: Create a new, empty Google Form by title.
- **Batch Update**: Add, move, or delete items and update form info via the Forms `batchUpdate` API.
- **List Responses**: Page through responses for a form, with optional time filter.
- **Get Response**: Fetch a single response by `responseId`.
- **Manage Watches**: Create, list, and delete Pub/Sub watches for `SCHEMA` or `RESPONSES` events.

## Installation

### Prerequisites

- Python 3.9 or higher.
- A Google Cloud Project with the **Google Forms API** and **Google Drive API** enabled.
- OAuth2 credentials (Client ID and Client Secret).
- OAuth scopes (defaults, used if `--scopes` not provided):
  - `https://www.googleapis.com/auth/forms.body` — read/write form structure
  - `https://www.googleapis.com/auth/forms.responses.readonly` — read form responses
  - `https://www.googleapis.com/auth/drive.readonly` — list forms via Drive

> The server's `list_forms` tool calls the Drive API, and `list_responses` / `get_response` call the Forms responses endpoint, so all three scopes are needed for full functionality.

### Local Setup

1. Install dependencies:
   ```bash
   pip install -e .
   ```

   The published wheel contains **`server.py`**, **`schemas.py`**, and **`tools/`** — not `main.py` (see below).

2. Run the server:
   ```bash
   python server.py \
     --access-token <ACCESS_TOKEN> \
     --refresh-token <REFRESH_TOKEN> \
     --client-id <CLIENT_ID> \
     --client-secret <CLIENT_SECRET>
   ```

   Optional flags:
   - `--expiry <ISO_TIMESTAMP>` — token expiry (e.g. `2026-05-07T12:00:00Z`).
   - `--scopes '["https://www.googleapis.com/auth/forms.body","https://www.googleapis.com/auth/forms.responses.readonly","https://www.googleapis.com/auth/drive.readonly"]'` — JSON array of scopes.
   - `--log-level DEBUG|INFO|WARNING|ERROR` — log verbosity (defaults to `INFO`).

   Environment variable fallbacks (used when the matching CLI flag is absent):
   - `GOOGLE_ACCESS_TOKEN`, `GOOGLE_REFRESH_TOKEN`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
   - `GOOGLE_TOKEN_EXPIRY`, `GOOGLE_SCOPES`, `LOG_LEVEL`

## Configuration

Add the following to your MCP host configuration (e.g., `mcp-config.json`):

```json
{
  "mcpServers": {
    "barie-google-forms-mcp": {
      "command": "uvx",
      "args": [
        "barie-google-forms-mcp",
        "--access-token",
        "YOUR_ACCESS_TOKEN",
        "--refresh-token",
        "YOUR_REFRESH_TOKEN",
        "--client-id",
        "YOUR_CLIENT_ID",
        "--client-secret",
        "YOUR_CLIENT_SECRET"
      ]
    }
  }
}
```

For local development against the source tree, use `uvx --from /path/to/google_forms barie-google-forms-mcp ...` instead.

## Optional: `main.py` (Barie monorepo only)

`main.py` is **not** shipped in the PyPI wheel. It wires this MCP server into CAMEL-AI (`camel.toolkits`) and Barie’s `mcp_use_service`. If you run it from a full monorepo checkout:

```bash
pip install -e ".[internal]"   # pulls python-dotenv; you still need camel-ai + Barie services on PYTHONPATH
```

If imports are missing, you will get an explicit `ImportError` telling you to use `barie-google-forms-mcp` / `python server.py` instead.

## Publishing (maintainers)

From this directory:

```bash
rm -rf dist/ build/ *.egg-info
python -m build
python -m twine check dist/*
# TestPyPI first (recommended):
# python -m twine upload --repository testpypi dist/*
```

## Tools

- `list_forms`: List Google Forms from Drive (optional `query`, `pageSize`, `pageToken`).
- `get_form`: Get form metadata, items, and settings by `formId`.
- `create_form`: Create a new, empty form with a `title`.
- `batch_update_form`: Apply a list of `requests` (e.g. `createItem`, `updateFormInfo`) to a form.
- `list_responses`: List responses for a form, with optional `filter`, `pageSize`, and `pageToken`.
- `get_response`: Get a single response by `formId` and `responseId`.
- `create_watch`: Create a Pub/Sub watch on a form (`eventType`: `SCHEMA` or `RESPONSES`).
- `list_watches`: List all watches for a form.
- `delete_watch`: Delete a watch by `formId` and `watchId`.

## Watch Tool Notes

`create_watch` requires a Google Cloud Pub/Sub topic and proper IAM bindings. Example payload:

```json
{
  "formId": "FORM_ID",
  "target": { "topic": { "topicName": "projects/PROJECT/topics/TOPIC" } },
  "eventType": "RESPONSES"
}
```

Allowed `eventType` values: `SCHEMA`, `RESPONSES`.

## Reliability

- Transient Google API errors (HTTP 429/500/502/503/504) are automatically retried up to 3 times with exponential backoff via `tenacity`.
- All Google API calls are dispatched off the asyncio event loop with `asyncio.to_thread` so the MCP server stays responsive.
- `HttpError`s are surfaced as `{"error": "Google API error <status>: <message>"}` instead of leaking internal tracebacks.

## License

MIT
