ldraney/groupme-mcp
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

Add list_dm_messages tool for reading DM thread history #9

New issue
Open
opened 2026-04-10 18:22:43 +00:00 by forgejo_admin · 0 comments
forgejo_admin commented 2026-04-10 18:22:43 +00:00
Contributor
Copy link

Type

Feature

Lineage

Standalone — discovered during 2026-04-10 Westside Ops session. While preparing Lucas for a meeting with Coach Marcus, I needed to read the full Marcus DM thread to understand what Marcus had asked for. The current groupme-mcp exposes list_dm_chats (which returns only the last-message preview) and send_dm, but no list_dm_messages tool for reading the conversation history. This left a gap where I could only see the single most recent line of a 26-message DM conversation.

Repo

forgejo_admin/groupme-mcp

User Story

As an operational agent working with Lucas on Westside tasks
I want to read the full message history of a GroupMe direct message thread
So that I can understand context, asks, and decisions Marcus has communicated privately — not just the latest message

Context

The GroupMe REST API exposes GET /v3/direct_messages which takes an other_user_id parameter and returns a paginated list of direct messages between the authenticated user and that user. Documentation: https://dev.groupme.com/docs/v3#direct_messages_index

The groupme-mcp currently wraps:

  • list_dm_chats — returns DM conversation list with last-message preview
  • send_dm — posts a new DM
  • (group-oriented tools: list_groups, list_messages, send_message, etc.)

Missing:

  • list_dm_messages — fetch message history for a specific DM thread

This is a straightforward addition. The group-oriented list_messages tool already exists as a model: it takes a group_name, limit, and before_id for pagination. The new list_dm_messages should follow the same pattern but take other_user_id (or optionally other_user_name resolved via list_dm_chats) instead of group_name.

File Targets

Files to modify:

  • src/groupme_mcp/tools/dm.py (or equivalent — wherever send_dm and list_dm_chats live) — add list_dm_messages tool implementation
  • src/groupme_mcp/server.py (or wherever tools are registered) — register the new tool
  • tests/test_dm.py — new tests for the tool
  • Check if groupme-sdk exposes a direct_messages() method — if not, that may need to be added there first as a dependency change

Files NOT to touch:

  • Existing group-message tools
  • OAuth / token handling

Acceptance Criteria

  • New MCP tool list_dm_messages is exposed and callable
  • Tool takes parameters: other_user_id (required), limit (default 20, max 100), before_id (optional for pagination)
  • Returns messages in reverse chronological order (newest first) matching the existing list_messages shape: id, sender, text, created_at
  • When called with a valid other_user_id from list_dm_chats, returns the full message history for that DM thread
  • When called with an invalid other_user_id, returns a clear error (not a traceback)
  • Pagination via before_id works — calling with the oldest returned id returns the next older batch
  • Tool schema is documented with a helpful description field so MCP clients know what it does
  • Existing tools continue to work

Test Expectations

  • Unit test: tests/test_dm.py::test_list_dm_messages_default_limit — mock GroupMe API, assert 20 messages returned
  • Unit test: tests/test_dm.py::test_list_dm_messages_pagination — assert before_id param is passed through correctly
  • Unit test: tests/test_dm.py::test_list_dm_messages_invalid_user — assert clean error for bad user_id
  • Integration test (optional, if test API token available): actually fetch a real DM thread
  • Run command: cd ~/groupme-mcp && pytest tests/test_dm.py -v

Constraints

  • Match the existing list_messages (group) tool signature and return shape for consistency
  • If groupme-sdk needs a new method first, that's a dependency — scope this ticket to the MCP addition and file a separate dependency ticket for the SDK if needed
  • Respect GroupMe API rate limits — don't auto-paginate past the requested limit
  • Must not break list_dm_chats or send_dm (both are actively used)

Checklist

  • PR opened
  • Unit tests pass
  • Integration test against real API if feasible
  • MCP tool schema includes clear description
  • No unrelated changes
  • Check if groupme-sdk needs a companion update

Related

  • westside-mcp — project this affects (if westside-mcp is where this MCP is hosted/tracked)
  • pal-e-platform — platform tooling umbrella
  • Use case: operational agents needing to read coach DMs to understand context during live sessions
### Type Feature ### Lineage Standalone — discovered during 2026-04-10 Westside Ops session. While preparing Lucas for a meeting with Coach Marcus, I needed to read the full Marcus DM thread to understand what Marcus had asked for. The current groupme-mcp exposes `list_dm_chats` (which returns only the last-message preview) and `send_dm`, but no `list_dm_messages` tool for reading the conversation history. This left a gap where I could only see the single most recent line of a 26-message DM conversation. ### Repo `forgejo_admin/groupme-mcp` ### User Story As an operational agent working with Lucas on Westside tasks I want to read the full message history of a GroupMe direct message thread So that I can understand context, asks, and decisions Marcus has communicated privately — not just the latest message ### Context The GroupMe REST API exposes `GET /v3/direct_messages` which takes an `other_user_id` parameter and returns a paginated list of direct messages between the authenticated user and that user. Documentation: https://dev.groupme.com/docs/v3#direct_messages_index The groupme-mcp currently wraps: - `list_dm_chats` — returns DM conversation list with last-message preview - `send_dm` — posts a new DM - (group-oriented tools: `list_groups`, `list_messages`, `send_message`, etc.) Missing: - `list_dm_messages` — fetch message history for a specific DM thread This is a straightforward addition. The group-oriented `list_messages` tool already exists as a model: it takes a `group_name`, limit, and `before_id` for pagination. The new `list_dm_messages` should follow the same pattern but take `other_user_id` (or optionally `other_user_name` resolved via `list_dm_chats`) instead of `group_name`. ### File Targets Files to modify: - `src/groupme_mcp/tools/dm.py` (or equivalent — wherever `send_dm` and `list_dm_chats` live) — add `list_dm_messages` tool implementation - `src/groupme_mcp/server.py` (or wherever tools are registered) — register the new tool - `tests/test_dm.py` — new tests for the tool - Check if groupme-sdk exposes a `direct_messages()` method — if not, that may need to be added there first as a dependency change Files NOT to touch: - Existing group-message tools - OAuth / token handling ### Acceptance Criteria - [ ] New MCP tool `list_dm_messages` is exposed and callable - [ ] Tool takes parameters: `other_user_id` (required), `limit` (default 20, max 100), `before_id` (optional for pagination) - [ ] Returns messages in reverse chronological order (newest first) matching the existing `list_messages` shape: `id`, `sender`, `text`, `created_at` - [ ] When called with a valid `other_user_id` from `list_dm_chats`, returns the full message history for that DM thread - [ ] When called with an invalid `other_user_id`, returns a clear error (not a traceback) - [ ] Pagination via `before_id` works — calling with the oldest returned `id` returns the next older batch - [ ] Tool schema is documented with a helpful `description` field so MCP clients know what it does - [ ] Existing tools continue to work ### Test Expectations - [ ] Unit test: `tests/test_dm.py::test_list_dm_messages_default_limit` — mock GroupMe API, assert 20 messages returned - [ ] Unit test: `tests/test_dm.py::test_list_dm_messages_pagination` — assert `before_id` param is passed through correctly - [ ] Unit test: `tests/test_dm.py::test_list_dm_messages_invalid_user` — assert clean error for bad user_id - [ ] Integration test (optional, if test API token available): actually fetch a real DM thread - Run command: `cd ~/groupme-mcp && pytest tests/test_dm.py -v` ### Constraints - Match the existing `list_messages` (group) tool signature and return shape for consistency - If groupme-sdk needs a new method first, that's a dependency — scope this ticket to the MCP addition and file a separate dependency ticket for the SDK if needed - Respect GroupMe API rate limits — don't auto-paginate past the requested limit - Must not break `list_dm_chats` or `send_dm` (both are actively used) ### Checklist - [ ] PR opened - [ ] Unit tests pass - [ ] Integration test against real API if feasible - [ ] MCP tool schema includes clear `description` - [ ] No unrelated changes - [ ] Check if groupme-sdk needs a companion update ### Related - `westside-mcp` — project this affects (if westside-mcp is where this MCP is hosted/tracked) - `pal-e-platform` — platform tooling umbrella - Use case: operational agents needing to read coach DMs to understand context during live sessions
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ldraney/groupme-mcp#9
No description provided.