Metadata-Version: 2.4
Name: groupme-mcp-server
Version: 0.1.0
Summary: A FastMCP server that exposes the GroupMe API v3 to MCP clients.
Keywords: fastmcp,groupme,llm,mcp,model-context-protocol
Author: Dariel Dato-on
Author-email: Dariel Dato-on <80038+oddrationale@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: fastmcp>=3.4.7,<4
Requires-Dist: pydantic-settings>=2.15,<3
Maintainer: Dariel Dato-on
Maintainer-email: Dariel Dato-on <80038+oddrationale@users.noreply.github.com>
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/oddrationale/groupme-mcp-server
Project-URL: Repository, https://github.com/oddrationale/groupme-mcp-server
Project-URL: Issues, https://github.com/oddrationale/groupme-mcp-server/issues
Project-URL: Changelog, https://github.com/oddrationale/groupme-mcp-server/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# groupme-mcp-server

[![CI](https://github.com/oddrationale/groupme-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/oddrationale/groupme-mcp-server/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/oddrationale/groupme-mcp-server/branch/main/graph/badge.svg)](https://codecov.io/gh/oddrationale/groupme-mcp-server)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/oddrationale/groupme-mcp-server/badge)](https://scorecard.dev/viewer/?uri=github.com/oddrationale/groupme-mcp-server)
[![PyPI](https://img.shields.io/pypi/v/groupme-mcp-server.svg)](https://pypi.org/project/groupme-mcp-server/)
[![Python](https://img.shields.io/pypi/pyversions/groupme-mcp-server.svg)](https://pypi.org/project/groupme-mcp-server/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

An [MCP](https://modelcontextprotocol.io) server that exposes the
[GroupMe API v3](https://dev.groupme.com/docs/v3) to MCP clients, built with
[FastMCP](https://gofastmcp.com) and hosted on
[Prefect Horizon](https://gofastmcp.com/deployment/prefect-horizon).

> **Status: scaffolding.** The project structure, tooling, and CI/CD are in
> place. No GroupMe tools are implemented yet.

## Quick start

```bash
uvx groupme-mcp-server
```

Or point an MCP client at it directly:

```json
{
  "mcpServers": {
    "groupme": {
      "command": "uvx",
      "args": ["groupme-mcp-server"],
      "env": {
        "GROUPME_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

## Configuration

All settings are read from the environment with the `GROUPME_MCP_` prefix, or
from a local `.env` file. See [`.env.example`](.env.example).

| Variable                 | Default | Description                                                     |
| ------------------------ | ------- | --------------------------------------------------------------- |
| `GROUPME_MCP_LOG_LEVEL`  | `INFO`  | `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`.              |

## Development

Requires [uv](https://docs.astral.sh/uv/) and Python 3.13+.

```bash
git clone https://github.com/oddrationale/groupme-mcp-server.git
cd groupme-mcp-server
uv sync --all-groups
uv run lefthook install     # install the git hooks
```

Common tasks:

| Command                          | What it does                                        |
| -------------------------------- | --------------------------------------------------- |
| `uv run ruff format .`           | Format.                                             |
| `uv run ruff check --fix .`      | Lint and autofix.                                   |
| `uv run ty check`                | Type check.                                         |
| `uv run pytest`                  | Run tests. **Fails below 100% coverage.**           |
| `uv run pytest --no-cov -k name` | Run a subset without the coverage gate.             |
| `uv run fastmcp inspect src/groupme_mcp_server/server.py:mcp` | See what Horizon sees. |

Coverage is enforced at **100%** (branch coverage included). If a line is
genuinely untestable, exclude it deliberately with `# pragma: no cover` and say
why in the PR — do not lower the threshold.

## Deployment

The server is live at **https://groupme.fastmcp.app/mcp**, deployed on
[Prefect Horizon](https://horizon.prefect.io), which builds directly from this
repository via its GitHub App.

- **Entrypoint:** `src/groupme_mcp_server/server.py:mcp`
- **Dependencies:** installed with `uv sync --frozen --no-dev`, so `uv.lock`
  must be committed and current or the build fails
- **Environment variables:** registered in the Horizon UI
- **Auth:** Horizon's built-in OAuth — clients must present a bearer token

The `production` target tracks `main` and deploys only after CI passes; every
pull request gets its own preview deployment. There is no deploy step in GitHub
Actions — CI gates quality and security, Horizon does the shipping.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues go through
[private vulnerability reporting](https://github.com/oddrationale/groupme-mcp-server/security/advisories/new),
not public issues — see [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE) © Dariel Dato-on
