Add DM and file attachment tools to GroupMe MCP

forgejo_admin commented

2026-03-28 19:03:04 +00:00

Owner

Type

Feature

Lineage

Discovered during girls roster session 2026-03-28. Had to use raw curl for DMs and file uploads because MCP only has group messaging.

Repo

forgejo_admin/groupme-mcp

User Story

As an agent, I want to send direct messages and file attachments via MCP tools so that I don't have to fall back to raw curl for GroupMe operations (GM-5).

Context

The GroupMe MCP currently has tools for groups (list, create, get), members (list, add, remove), and messages (send, list). Missing: DMs and file attachments. Both endpoints work via the GroupMe API but are undocumented.

API discoveries from this session:

POST /direct_messages with recipient_id + text sends DMs
GET /chats lists DM conversations
POST file.groupme.com/v1/{group_id}/files uploads files (any type)
Poll GET file.groupme.com/v1/{group_id}/uploadStatus?job={id} for upload completion
Send file with {"type": "file", "file_id": "..."} attachment
Initial DMs block anything resembling links/emails (422 error). Workaround: obfuscate with (at) and (dot) com

See project-groupme-westside Known Behaviors section for full documentation.

File Targets

Files the agent should create/modify:

src/groupme_mcp/tools/direct_messages.py -- new tool: send_dm(recipient_id, text), list_dm_chats()
src/groupme_mcp/tools/files.py -- new tool: upload_file(group_name, file_path), returns file_id for attachment
src/groupme_mcp/tools/messages.py -- extend send_message to accept optional attachments param (file_id or image_url)
src/groupme_mcp/server.py -- register new tools

Files the agent should NOT touch:

groups.py, members.py (no changes needed)

Acceptance Criteria

send_dm(recipient_id, text) sends a direct message and returns message data
list_dm_chats() returns list of DM conversations with last message
upload_file(group_name, file_path) uploads a file and returns file_id
send_message supports optional file/image attachments
All tools handle GroupMe error responses gracefully (422 link restriction, etc)

Test Expectations

Unit tests for each new tool
Integration test with real GroupMe API (manual)
Run command: pytest tests/

Constraints

Follow existing tool patterns in groups.py/members.py/messages.py
Use GROUPME_ACCESS_TOKEN env var (already configured)
Document the link restriction workaround in tool docstrings

Checklist

PR opened
Tests pass
No unrelated changes

project-groupme-westside -- parent project
board-westside-basketball -- tracking board

### Type Feature ### Lineage Discovered during girls roster session 2026-03-28. Had to use raw curl for DMs and file uploads because MCP only has group messaging. ### Repo `forgejo_admin/groupme-mcp` ### User Story As an agent, I want to send direct messages and file attachments via MCP tools so that I don't have to fall back to raw curl for GroupMe operations (GM-5). ### Context The GroupMe MCP currently has tools for groups (list, create, get), members (list, add, remove), and messages (send, list). Missing: DMs and file attachments. Both endpoints work via the GroupMe API but are undocumented. API discoveries from this session: - `POST /direct_messages` with `recipient_id` + `text` sends DMs - `GET /chats` lists DM conversations - `POST file.groupme.com/v1/{group_id}/files` uploads files (any type) - Poll `GET file.groupme.com/v1/{group_id}/uploadStatus?job={id}` for upload completion - Send file with `{"type": "file", "file_id": "..."}` attachment - Initial DMs block anything resembling links/emails (422 error). Workaround: obfuscate with `(at)` and `(dot) com` See `project-groupme-westside` Known Behaviors section for full documentation. ### File Targets Files the agent should create/modify: - `src/groupme_mcp/tools/direct_messages.py` -- new tool: `send_dm(recipient_id, text)`, `list_dm_chats()` - `src/groupme_mcp/tools/files.py` -- new tool: `upload_file(group_name, file_path)`, returns file_id for attachment - `src/groupme_mcp/tools/messages.py` -- extend `send_message` to accept optional `attachments` param (file_id or image_url) - `src/groupme_mcp/server.py` -- register new tools Files the agent should NOT touch: - groups.py, members.py (no changes needed) ### Acceptance Criteria - [ ] `send_dm(recipient_id, text)` sends a direct message and returns message data - [ ] `list_dm_chats()` returns list of DM conversations with last message - [ ] `upload_file(group_name, file_path)` uploads a file and returns file_id - [ ] `send_message` supports optional file/image attachments - [ ] All tools handle GroupMe error responses gracefully (422 link restriction, etc) ### Test Expectations - [ ] Unit tests for each new tool - [ ] Integration test with real GroupMe API (manual) - Run command: `pytest tests/` ### Constraints - Follow existing tool patterns in groups.py/members.py/messages.py - Use `GROUPME_ACCESS_TOKEN` env var (already configured) - Document the link restriction workaround in tool docstrings ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-groupme-westside` -- parent project - `board-westside-basketball` -- tracking board

forgejo_admin commented

2026-03-28 19:08:47 +00:00

Author

Owner

Scope Review: NEEDS_REFINEMENT

Review note: review-586-2026-03-28
Story label mismatch and undocumented SDK dependency require resolution before execution.

[LABEL] story:WS-S6 is wrong (draft board story). Should be story:GM-5 (MCP tooling story).
[SCOPE] groupme-sdk has no DM or file methods. Decide: (a) split into SDK issue + MCP issue, or (b) scope raw HTTP calls in MCP (breaking SDK pattern).
[BODY] Add SDK dependency or raw-HTTP constraint to issue body.
[DECOMPOSE] If SDK route chosen: 2 sequential tickets needed (SDK first, MCP second). Recommend decomposition via template-board.

## Scope Review: NEEDS_REFINEMENT Review note: `review-586-2026-03-28` Story label mismatch and undocumented SDK dependency require resolution before execution. - **[LABEL]** `story:WS-S6` is wrong (draft board story). Should be `story:GM-5` (MCP tooling story). - **[SCOPE]** groupme-sdk has no DM or file methods. Decide: (a) split into SDK issue + MCP issue, or (b) scope raw HTTP calls in MCP (breaking SDK pattern). - **[BODY]** Add SDK dependency or raw-HTTP constraint to issue body. - **[DECOMPOSE]** If SDK route chosen: 2 sequential tickets needed (SDK first, MCP second). Recommend decomposition via template-board.