spike: inventory Penny MCP services and fix stale penny.md #204

Merged

forgejo_admin merged 1 commit from 133-spike-penny-mcp-inventory into main

2026-03-28 11:30:20 +00:00

forgejo_admin commented

2026-03-28 06:04:44 +00:00

Contributor

Summary

Spike investigation of Penny's MCP service landscape. Found Gmail and GroupMe are already deployed and active but were missing from penny.md. Fixed penny.md to reflect reality and documented all 10 MCP services with auth types, credential locations, and deployment status.

Changes

agents/penny.md -- Added gmail and groupme to mcpServers frontmatter, added Gmail/GroupMe to Access table and MCP Tools table, replaced stale "Future MCP Servers (not yet deployed)" section with accurate "MCP Servers Not Yet Wired" section listing only gcal-mcp and linkedin-mcp-scheduler
spikes/133-penny-mcp-inventory.md -- Complete spike findings: 8 deployed servers, 2 unwired gaps, OAuth token inventory, wiring instructions for each gap, plugin relevance assessment

Spike Findings

Deployed and active (8 servers): pal-e-docs, notion, gmail, groupme, forgejo, woodpecker, playwright, chrome-devtools. Of these, Penny has access to pal-e-docs (read-only), notion (full), gmail (with approval gate), groupme (with approval gate).

Not wired (2 gaps):

gcal-mcp -- Repo and credentials exist. Blocker: token symlink missing (~/secrets/google-oauth/token.json needs to point to desktop/token.json), then add ~/.mcp.json entry.
linkedin-mcp-scheduler -- Repo and credentials exist. Blocker: needs ~/.mcp.json entry with LINKEDIN_ACCESS_TOKEN and LINKEDIN_PERSON_ID env vars from ~/secrets/linkedin/credentials.env.

Plugins assessed: 17 external plugins in marketplace. None currently relevant to Penny. Slack/Discord/Telegram could become relevant if adopted.

Follow-up Tickets Created

#202 -- Wire gcal-mcp to ~/.mcp.json
#203 -- Wire linkedin-mcp-scheduler to ~/.mcp.json

Test Plan

Verify penny.md frontmatter YAML parses correctly (mcpServers list, disallowedTools unchanged)
Verify Access table and MCP Tools table are consistent with mcpServers list
Verify spike findings match actual ~/.mcp.json contents and filesystem state
Verify follow-up tickets #202 and #203 have actionable wiring instructions

Review Checklist

penny.md mcpServers frontmatter matches actually deployed servers
penny.md Access table and MCP Tools table are consistent
Spike inventory covers all 8 deployed + 2 unwired servers
OAuth token inventory is accurate (auth types, locations, expiry risk)
Wiring instructions in spike doc are actionable
Follow-up tickets #202 and #203 have complete scope

agent-penny -- Penny agent definition in pal-e-docs (source of truth for penny.md)

Closes #133

Dependency: #132 (Penny agent type fix, closed)
Follow-ups: #202 (gcal wiring), #203 (linkedin wiring)

## Summary Spike investigation of Penny's MCP service landscape. Found Gmail and GroupMe are already deployed and active but were missing from penny.md. Fixed penny.md to reflect reality and documented all 10 MCP services with auth types, credential locations, and deployment status. ## Changes - `agents/penny.md` -- Added `gmail` and `groupme` to mcpServers frontmatter, added Gmail/GroupMe to Access table and MCP Tools table, replaced stale "Future MCP Servers (not yet deployed)" section with accurate "MCP Servers Not Yet Wired" section listing only gcal-mcp and linkedin-mcp-scheduler - `spikes/133-penny-mcp-inventory.md` -- Complete spike findings: 8 deployed servers, 2 unwired gaps, OAuth token inventory, wiring instructions for each gap, plugin relevance assessment ## Spike Findings **Deployed and active (8 servers):** pal-e-docs, notion, gmail, groupme, forgejo, woodpecker, playwright, chrome-devtools. Of these, Penny has access to pal-e-docs (read-only), notion (full), gmail (with approval gate), groupme (with approval gate). **Not wired (2 gaps):** - **gcal-mcp** -- Repo and credentials exist. Blocker: token symlink missing (`~/secrets/google-oauth/token.json` needs to point to `desktop/token.json`), then add `~/.mcp.json` entry. - **linkedin-mcp-scheduler** -- Repo and credentials exist. Blocker: needs `~/.mcp.json` entry with `LINKEDIN_ACCESS_TOKEN` and `LINKEDIN_PERSON_ID` env vars from `~/secrets/linkedin/credentials.env`. **Plugins assessed:** 17 external plugins in marketplace. None currently relevant to Penny. Slack/Discord/Telegram could become relevant if adopted. ## Follow-up Tickets Created - #202 -- Wire gcal-mcp to ~/.mcp.json - #203 -- Wire linkedin-mcp-scheduler to ~/.mcp.json ## Test Plan - Verify penny.md frontmatter YAML parses correctly (mcpServers list, disallowedTools unchanged) - Verify Access table and MCP Tools table are consistent with mcpServers list - Verify spike findings match actual `~/.mcp.json` contents and filesystem state - Verify follow-up tickets #202 and #203 have actionable wiring instructions ## Review Checklist - [ ] penny.md mcpServers frontmatter matches actually deployed servers - [ ] penny.md Access table and MCP Tools table are consistent - [ ] Spike inventory covers all 8 deployed + 2 unwired servers - [ ] OAuth token inventory is accurate (auth types, locations, expiry risk) - [ ] Wiring instructions in spike doc are actionable - [ ] Follow-up tickets #202 and #203 have complete scope ## Related Notes - `agent-penny` -- Penny agent definition in pal-e-docs (source of truth for penny.md) ## Related Closes #133 - Dependency: #132 (Penny agent type fix, closed) - Follow-ups: #202 (gcal wiring), #203 (linkedin wiring)

forgejo_admin added 1 commit

2026-03-28 06:04:44 +00:00

spike: inventory Penny MCP services and fix stale penny.md (#133 ) 3baebccebd

Investigated all MCP services relevant to Penny's communication role.
Found Gmail and GroupMe are already deployed and active but missing from
penny.md frontmatter. Fixed penny.md to reflect reality and created
follow-up tickets #202 (gcal-mcp wiring) and #203 (linkedin-mcp wiring)
for the two remaining gaps.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

forgejo_admin commented

2026-03-28 11:29:16 +00:00

Author

Contributor

PR #204 Review

DOMAIN REVIEW

Domain: Agent configuration (Markdown/YAML frontmatter)

This is a documentation-only PR: one agent config file update (agents/penny.md) and one new spike investigation document (spikes/133-penny-mcp-inventory.md). No executable code, no infrastructure changes, no application code. The review focuses on accuracy, consistency, and documentation quality.

penny.md changes:

Adds gmail and groupme to the mcpServers YAML frontmatter list -- consistent with the existing list format.
Adds two rows to the Access table with appropriate permission levels and approval gate annotations.
Adds two rows to the MCP Tools table with wildcard patterns (mcp__gmail__*, mcp__groupme__*) matching the existing mcp__notion__* pattern.
Replaces stale "Future MCP Servers (not yet deployed)" section with "MCP Servers Not Yet Wired" -- adds a Blocker column to the table, removes gmail-mcp (now correctly reflected as deployed), and updates status from "NOT DEPLOYED" to "NOT WIRED" for the remaining two.

The penny.md changes are clean and internally consistent. The frontmatter, Access table, and MCP Tools table all agree.

Spike document:

Thorough inventory of all 10 MCP services with auth types, credential locations, and deployment status.
OAuth token inventory with expiry risk assessment.
Actionable wiring instructions for the two gaps (gcal-mcp, linkedin-mcp-scheduler).
Plugin relevance assessment of 17 external plugins.

BLOCKERS

None.

This is a documentation-only PR. The BLOCKER criteria (test coverage for new functionality, unvalidated user input, secrets in code, DRY auth violations) do not apply to Markdown documentation changes.

Secrets review: The spike document references credential locations (filesystem paths like ~/secrets/google-oauth/) but does NOT contain any actual secrets, tokens, API keys, or passwords. The ~/.mcp.json examples in the wiring instructions use placeholder text (<from ~/secrets/linkedin/credentials.env>) rather than real values. This is correct.

NITS

Typo in credential filename (spikes/133-penny-mcp-inventory.md, line 3 of Gmail row): gmail-westsidebasktball.json -- missing the letter 'e' in "basketball." This appears twice in the spike doc (OAuth Token Inventory table and Deployed servers table). Should be gmail-westsidebasketball.json. Worth verifying whether the actual filename on disk also has this typo (in which case the doc is correct but the file should be renamed).
New directory convention: This PR introduces a spikes/ directory that did not previously exist in the repo. This seems like a reasonable convention for spike investigation artifacts, but it is not documented anywhere in the repo. Consider whether a brief note in the README or a convention doc should acknowledge this directory.
Escaped JSON in spike wiring instructions: The JSON examples in the spike doc have escaped quotes (\\\"gcal\\\") which is an artifact of the diff rendering. If the actual file content has literal backslash-quotes rather than plain quotes, the JSON examples would not be valid copy-paste targets. (This is likely a diff rendering issue, not an actual file issue, but worth confirming.)

SOP COMPLIANCE

Branch named after issue: 133-spike-penny-mcp-inventory references issue #133
PR body has ## Summary, ## Changes, ## Test Plan, ## Related
Related section references the parent issue: "Closes #133"
No secrets committed -- only filesystem paths to credential locations, no actual values
No unnecessary file changes -- both files are directly related to the spike scope
Commit messages: not visible in diff, but PR title is descriptive
Related references plan slug: No plan slug referenced, but this is a spike (investigation), not plan-driven work. The PR body does reference the parent issue and dependency (#132) and follow-ups (#202, #203). Acceptable for spike-type work.

PROCESS OBSERVATIONS

Good spike discipline: investigation completed, findings documented, follow-up tickets (#202, #203) created with actionable scope. The spike closes cleanly with no loose ends.
The PR body includes a Review Checklist which is a nice quality signal beyond the standard template.
The penny.md changes are minimal and surgical -- only the lines affected by the spike findings are changed. No scope creep.
DORA impact: Low risk. Documentation-only changes with no deployment or runtime impact. Change failure risk is effectively zero.

VERDICT: APPROVED

## PR #204 Review ### DOMAIN REVIEW **Domain: Agent configuration (Markdown/YAML frontmatter)** This is a documentation-only PR: one agent config file update (`agents/penny.md`) and one new spike investigation document (`spikes/133-penny-mcp-inventory.md`). No executable code, no infrastructure changes, no application code. The review focuses on accuracy, consistency, and documentation quality. **penny.md changes:** - Adds `gmail` and `groupme` to the `mcpServers` YAML frontmatter list -- consistent with the existing list format. - Adds two rows to the Access table with appropriate permission levels and approval gate annotations. - Adds two rows to the MCP Tools table with wildcard patterns (`mcp__gmail__*`, `mcp__groupme__*`) matching the existing `mcp__notion__*` pattern. - Replaces stale "Future MCP Servers (not yet deployed)" section with "MCP Servers Not Yet Wired" -- adds a Blocker column to the table, removes `gmail-mcp` (now correctly reflected as deployed), and updates status from "NOT DEPLOYED" to "NOT WIRED" for the remaining two. The penny.md changes are clean and internally consistent. The frontmatter, Access table, and MCP Tools table all agree. **Spike document:** - Thorough inventory of all 10 MCP services with auth types, credential locations, and deployment status. - OAuth token inventory with expiry risk assessment. - Actionable wiring instructions for the two gaps (gcal-mcp, linkedin-mcp-scheduler). - Plugin relevance assessment of 17 external plugins. ### BLOCKERS None. This is a documentation-only PR. The BLOCKER criteria (test coverage for new functionality, unvalidated user input, secrets in code, DRY auth violations) do not apply to Markdown documentation changes. **Secrets review:** The spike document references credential *locations* (filesystem paths like `~/secrets/google-oauth/`) but does NOT contain any actual secrets, tokens, API keys, or passwords. The `~/.mcp.json` examples in the wiring instructions use placeholder text (`<from ~/secrets/linkedin/credentials.env>`) rather than real values. This is correct. ### NITS 1. **Typo in credential filename** (`spikes/133-penny-mcp-inventory.md`, line 3 of Gmail row): `gmail-westsidebasktball.json` -- missing the letter 'e' in "basketball." This appears twice in the spike doc (OAuth Token Inventory table and Deployed servers table). Should be `gmail-westsidebasketball.json`. Worth verifying whether the actual filename on disk also has this typo (in which case the doc is correct but the file should be renamed). 2. **New directory convention**: This PR introduces a `spikes/` directory that did not previously exist in the repo. This seems like a reasonable convention for spike investigation artifacts, but it is not documented anywhere in the repo. Consider whether a brief note in the README or a convention doc should acknowledge this directory. 3. **Escaped JSON in spike wiring instructions**: The JSON examples in the spike doc have escaped quotes (`\\\"gcal\\\"`) which is an artifact of the diff rendering. If the actual file content has literal backslash-quotes rather than plain quotes, the JSON examples would not be valid copy-paste targets. (This is likely a diff rendering issue, not an actual file issue, but worth confirming.) ### SOP COMPLIANCE - [x] Branch named after issue: `133-spike-penny-mcp-inventory` references issue #133 - [x] PR body has ## Summary, ## Changes, ## Test Plan, ## Related - [x] Related section references the parent issue: "Closes #133" - [x] No secrets committed -- only filesystem paths to credential locations, no actual values - [x] No unnecessary file changes -- both files are directly related to the spike scope - [x] Commit messages: not visible in diff, but PR title is descriptive - [ ] Related references plan slug: No plan slug referenced, but this is a spike (investigation), not plan-driven work. The PR body does reference the parent issue and dependency (#132) and follow-ups (#202, #203). Acceptable for spike-type work. ### PROCESS OBSERVATIONS - Good spike discipline: investigation completed, findings documented, follow-up tickets (#202, #203) created with actionable scope. The spike closes cleanly with no loose ends. - The PR body includes a Review Checklist which is a nice quality signal beyond the standard template. - The penny.md changes are minimal and surgical -- only the lines affected by the spike findings are changed. No scope creep. - DORA impact: Low risk. Documentation-only changes with no deployment or runtime impact. Change failure risk is effectively zero. ### VERDICT: APPROVED