@cohortapp/agent-sdk 2.3.0

package/docs/architecture/mcp-capability-map.md

@@ -0,0 +1,585 @@
+# MCP Capability Map
+
+**Scope:** one Maestro agent instance
+**Updated:** 2026-04-02
+**Status:** Illustrative (this example shows 28 of 30 integrations active)
+
+This document is the reference template for everything a Maestro agent can do
+through its connected MCP servers and local tooling. It maps capabilities to
+operational domains and identifies gaps.
+
+The capability surface is not fixed — it is generated per agent from the chosen
+archetype. The domains, tool packs, and MCP servers below are the ones a given
+role needs; a different `{ function, altitude }` resolves to a different set. See
+[The Archetype Agent Factory](archetype-agent-factory.md) for how the role's
+capability pack (sub-agents, skills, workflows, MCP servers) is composed. The
+worked example throughout this page is a **Chief of Staff** agent — one archetype
+among many — kept only to make the mapping concrete.
+
+---
+
+## Integration Summary
+
+| Category          | Connected | Needs Auth | Failed | Total  |
+| ----------------- | --------- | ---------- | ------ | ------ |
+| Cloud MCP servers | 23        | 1          | 1      | 25     |
+| Local MCP servers | 5         | 0          | 0      | 5      |
+| **Total**         | **28**    | **1**      | **1**  | **30** |
+
+---
+
+## 1. Communications
+
+The agent is the communications hub for the company. It can read, write, and
+manage messages across all primary channels.
+
+### What the agent can do
+
+**Slack (connected)**
+
+- Send and receive messages in any Slack channel
+- Monitor priority channels continuously (the channel set is configured per agent — e.g. an exec office channel, a remediation channel, engineering, strategy, legal)
+- Auto-respond to @-mentions and DMs
+- Post morning briefs, triage summaries, and status updates
+- Manage threads, reactions, and channel-level coordination
+
+**Gmail (connected)**
+
+- Read, search, and triage the agent's inbox
+- Send emails in the agent's voice (warm, professional, direct)
+- Draft and send outreach, rejections, and acknowledgements
+- Distribute principal-facing updates and board materials
+- Search email history for context on any conversation
+
+**Google Calendar (connected)**
+
+- View and manage calendars for scheduling
+- Create, update, and cancel events
+- Check availability across timezones (multi-office org)
+- Block focus time and manage meeting cadence
+
+### Rate Limits
+
+- 30 messages/sends per hour
+- 200 messages/sends per day
+
+---
+
+## 2. Hiring and Recruitment
+
+A Chief of Staff archetype manages end-to-end hiring operations across the org's
+open roles, departments, and offices. (Other archetypes drop this domain
+entirely.)
+
+### What the agent can do
+
+**Metaview (connected)**
+
+- Capture AI-generated interview notes and transcriptions automatically
+- Generate structured interview scorecards
+- Identify patterns across interviews for calibration
+- Archive interview records for compliance
+
+**Calendly (connected)**
+
+- Schedule candidate interviews with self-service booking links
+- Manage interviewer availability and round-robin assignments
+- Coordinate multi-stage interview loops (screen, technical, executive)
+
+**Airtable (connected)**
+
+- Track the full hiring pipeline across all open roles
+- Manage candidate records with screening scores and stage progression
+- Generate hiring metrics and pipeline health reports
+- Maintain department-level and location-level dashboards
+
+**Gmail (connected)**
+
+- Send candidate outreach using approved templates
+- Deliver gentle, specific rejections for closed candidates
+- Coordinate offer discussions (requires principal approval)
+- Acknowledge applications within SLA (24-48 hours)
+
+**Zapier (connected)**
+
+- Ingest LinkedIn applications into Airtable automatically
+- Sync pipeline updates across tools
+- Trigger notifications for the hiring team
+
+### Approval Chain
+
+| Action                           | Approval Level                            |
+| -------------------------------- | ----------------------------------------- |
+| Candidate advance (score >= 75)  | Pre-approved                              |
+| Candidate rejection (score < 40) | Pre-approved                              |
+| Candidate hold (score 40-74)     | Pre-approved (acknowledge)                |
+| Offer discussion                 | Principal approval required               |
+| Org chart changes                | Principal approval required               |
+| LinkedIn job posting             | Pre-approved (approved descriptions only) |
+
+---
+
+## 3. Strategy and Intelligence
+
+The agent gathers and synthesizes intelligence across academic, market, and web
+sources to support strategic decision-making.
+
+### What the agent can do
+
+**Consensus (connected)**
+
+- Search academic and scientific papers on any topic
+- Find evidence-based research for regulatory, M&A, and market strategy
+- Source papers in the agent's domain (e.g. quantitative trading, compliance frameworks, fintech trends)
+
+**LunarCrush (connected)**
+
+- Monitor real-time crypto and digital asset market sentiment
+- Track social media buzz around competitors and market segments
+- Generate market intelligence summaries
+
+**WebSearch (built-in)**
+
+- Search the web for current news, competitor information, and market data
+- Research regulatory developments and industry trends
+- Find public information on M&A targets
+
+**WebFetch (built-in)**
+
+- Fetch and read specific web pages for deep-dive analysis
+- Download regulatory documents, company filings, and press releases
+
+**Granted (connected)**
+
+- Search government grants applicable to the company's sector
+- Identify R&D tax credits and innovation funding programs
+- Find regulatory sandbox opportunities
+
+**Memory (local MCP)**
+
+- Store accumulated strategic insights in a persistent knowledge graph
+- Retrieve past research and analysis for continuity
+
+---
+
+## 4. Project Management
+
+The agent tracks and coordinates projects across the company's strategic
+priorities.
+
+### What the agent can do
+
+**Linear (connected)**
+
+- Create, update, assign, and close issues
+- Track remediation gaps and compliance workstreams
+- Monitor sprint progress, velocity, and blockers
+- Generate project status reports for leadership
+- Manage cross-team dependencies and escalations
+
+**Airtable (connected)**
+
+- Track non-engineering projects (hiring, deals, regulatory milestones)
+- Manage cross-functional databases and tracking tables
+- Generate flexible reports and dashboards
+- Maintain deal / pipeline tracking tables
+
+**GitHub (local MCP)**
+
+- Monitor repositories, pull requests, and code-level issues
+- Track engineering activity across the company's codebases
+- Coordinate code review and merge workflows
+
+---
+
+## 5. Board and Investor Relations
+
+The agent prepares board materials, investor updates, and capital raising
+presentations.
+
+### What the agent can do
+
+**Gamma (connected)**
+
+- Create professional board meeting decks from scratch
+- Build investor pitch presentations for capital raising
+- Generate strategy presentations for M&A target engagement
+- Create quarterly business review slide decks
+
+**Lumin (connected)**
+
+- Review and annotate board materials in PDF format
+- Mark up term sheets, investment memoranda, and governance documents
+- Manage document versions and review cycles
+
+**Mermaid Chart (connected)**
+
+- Generate organizational charts for the growing team
+- Create architecture diagrams for technical board materials
+- Build process flow diagrams and timeline visualizations
+- Create deal pipeline and dependency visualizations
+
+**Canva (connected)**
+
+- Polish presentation assets and one-pagers
+- Create investor-facing branded materials
+- Design visual summaries and infographics
+
+### Approval Requirement
+
+All board and investor materials require the principal's explicit approval before
+distribution. No investor communication goes out without principal sign-off.
+
+---
+
+## 6. Legal
+
+The agent handles legal document review, annotation, and coordination. In this
+example instance, the domain is operating at reduced capability.
+
+### What the agent can do
+
+**Lumin (connected)**
+
+- Review and annotate regulatory documents
+- Mark up contracts, term sheets, and legal agreements
+- Track document versions and flag key terms and risks
+- Manage PDF review workflows with legal counsel
+
+### What the agent cannot yet do
+
+**LegalZoom (NEEDS AUTH)**
+
+- Draft corporate governance documents
+- Create employment agreement templates
+- Generate NDAs and entity formation documents
+- _Status: Requires authentication before use_
+
+**DocuSign (FAILED)**
+
+- Send contracts for digital signature
+- Track signature status on outstanding documents
+- Manage signing workflows
+- _Status: Connection failed. Needs troubleshooting._
+- _Workaround: Manual signature process via email_
+
+---
+
+## 7. Meetings
+
+The agent manages the full meeting lifecycle from scheduling through follow-up.
+
+### What the agent can do
+
+**Granola (connected)**
+
+- Automatically transcribe and summarize all meetings
+- Extract action items with owners and deadlines
+- Generate structured notes for board meetings and investor calls
+- Track commitments across recurring meetings
+
+**Calendly (connected)**
+
+- Provide self-service scheduling links for external parties
+- Manage interview scheduling across timezones
+- Coordinate multi-party meeting booking
+
+**Google Calendar (connected)**
+
+- Schedule internal meetings with availability checking
+- Block preparation and follow-up time
+- Manage recurring meeting cadences
+- Coordinate across the org's office timezones
+
+### Meeting Intelligence Pipeline
+
+Granola meeting notes feed into: morning briefs, Linear action items, weekly
+reports, and the Memory knowledge graph for institutional continuity.
+
+---
+
+## 8. Design and Brand
+
+The agent can create, review, and coordinate visual and design assets.
+
+### What the agent can do
+
+**Canva (connected)**
+
+- Create branded social media graphics for hiring campaigns
+- Design marketing collateral and visual assets
+- Build branded templates for reports and communications
+- Generate infographics for internal and external use
+
+**Figma (connected)**
+
+- Review product and UI designs with structured feedback
+- Comment on UX flows for the company's product surfaces
+- Coordinate design-to-engineering handoffs
+- Track design progress on regulated / compliance-related features
+
+**tldraw (connected)**
+
+- Quick sketches and wireframes during planning sessions
+- Visual brainstorming and concept exploration
+- Rough diagram creation before formal Mermaid/Gamma output
+
+---
+
+## 9. Travel
+
+The agent can plan and book business travel across the org's offices.
+
+### What the agent can do
+
+**Kiwi.com (connected)**
+
+- Search and compare flights across all routes
+- Book single and multi-city itineraries
+- Find options for investor roadshow travel
+
+**lastminute.com (connected)**
+
+- Search travel packages combining flights and hotels
+- Find last-minute deals for urgent travel
+- Compare package vs. separate booking pricing
+
+**DirectBooker (connected)**
+
+- Book hotels near the company's offices worldwide
+- Find accommodation with conference facilities
+- Book extended stays for relocations and assignments
+
+### Approval Requirement
+
+All travel bookings require explicit approval before purchase. The agent presents
+options with pricing but does not book without confirmation.
+
+---
+
+## 10. Automation
+
+Zapier is the agent's universal connector, bridging tools that do not natively
+integrate.
+
+### What the agent can do
+
+**Zapier (connected)**
+
+- Create cross-platform automations between any connected tools
+- Automate LinkedIn-to-Airtable candidate pipeline ingestion
+- Trigger Slack notifications from Linear status changes
+- Sync data across Airtable, Gmail, Slack, and Calendar
+- Build custom workflows for novel operational needs
+
+### Key Active Automations
+
+- LinkedIn applications -> Airtable hiring pipeline -> Slack notification
+- Linear issue status change -> Slack channel update
+- Granola meeting action items -> Linear issue creation
+- Calendly booking -> Google Calendar event
+
+---
+
+## 11. Engineering
+
+The agent coordinates engineering operations without writing production code
+directly.
+
+### What the agent can do
+
+**Netlify (connected)**
+
+- Deploy updates to web properties (marketing site, careers page)
+- Monitor deployment status and build logs
+- Manage preview deployments for content changes
+- Rollback deployments if critical issues are detected
+
+**Jam (connected)**
+
+- Capture bug reports with visual screenshots and recordings
+- Create detailed reproduction steps
+- Route bug reports to Linear for engineering tracking
+
+**Context7 (connected)**
+
+- Look up current library and framework documentation
+- Verify API patterns and technical best practices
+- Provide technical context for architecture discussions
+
+**GitHub (local MCP)**
+
+- Manage repositories, branches, and pull requests
+- Track engineering activity and code review status
+- Coordinate across the company's codebases
+
+**Bash (local)**
+
+- Run build scripts and local tooling
+- Execute the agent repo's operational scripts
+- Manage local file system and development environment
+
+---
+
+## 12. Research
+
+The agent conducts deep research across multiple source types to support all
+operational domains.
+
+### What the agent can do
+
+**Consensus (connected)**
+
+- Academic paper search across all scientific disciplines
+- Evidence-based research for regulatory and strategic decisions
+
+**WebSearch (built-in)**
+
+- Real-time web search for current information
+- Competitive intelligence and market monitoring
+
+**WebFetch (built-in)**
+
+- Deep-read specific web pages, documents, and filings
+
+**LunarCrush (connected)**
+
+- Market sentiment and social intelligence for crypto/digital assets
+
+**Granted (connected)**
+
+- Government grant and non-dilutive funding search
+
+**Memory (local MCP)**
+
+- Persistent knowledge storage and retrieval
+- Accumulated research insights across sessions
+
+---
+
+## What Is NOT Yet Available
+
+### Integrations Requiring Action
+
+| Tool          | Issue                | Impact                                      | Workaround                                       |
+| ------------- | -------------------- | ------------------------------------------- | ------------------------------------------------ |
+| **LegalZoom** | Needs authentication | Cannot draft legal documents via MCP        | Draft manually or via external counsel           |
+| **DocuSign**  | Connection failed    | Cannot send contracts for digital signature | Manual wet signature or external DocuSign portal |
+
+### Capabilities Not Yet Covered by Any Integration
+
+| Capability                      | Gap                                          | Potential Solution                                   |
+| ------------------------------- | -------------------------------------------- | ---------------------------------------------------- |
+| **CRM / Sales Pipeline**        | No CRM integration (Salesforce, HubSpot)     | Airtable as interim; consider CRM MCP when available |
+| **Financial Data / Accounting** | No accounting integration (QuickBooks, Xero) | Manual financial tracking; consider integration      |
+| **HR/Payroll System**           | No HRIS integration (BambooHR, Rippling)     | Manual HR processes; Airtable as interim tracker     |
+| **Cloud Infrastructure**        | No AWS/GCP/Azure MCP integration             | Managed via Bash/CLI; consider cloud MCP servers     |
+| **WhatsApp Business**           | Desktop control only, no MCP                 | Use desktop control AppleScript fallback             |
+| **Video Conferencing**          | No Zoom/Teams MCP integration                | Use Google Calendar links + Granola for capture      |
+| **Knowledge Base / Wiki**       | No Notion/Confluence MCP integration         | Agent repo filesystem serves as knowledge base       |
+| **Customer Support**            | No Zendesk/Intercom integration              | Not yet needed at current stage                      |
+| **Analytics / BI**              | No Mixpanel/Amplitude/Looker integration     | Airtable dashboards as interim                       |
+| **Password/Secrets Management** | No 1Password/Vault integration               | Environment variables per config/environment.yaml    |
+
+### Auth and Connection Issues to Resolve
+
+1. **LegalZoom** -- Complete authentication flow to enable legal document drafting
+2. **DocuSign** -- Debug and re-establish failed connection for contract signing
+3. **LinkedIn (via Zapier)** -- Verify Zapier-LinkedIn automation is active and syncing
+
+---
+
+## Capability Matrix by Strategic Priority
+
+How the agent's tools map to the company's active strategic priorities. The
+priorities below are illustrative for the Chief of Staff example; each agent's
+priorities are generated from its archetype and context pack.
+
+### P1: Regulatory Submission (Critical)
+
+| Need                    | Tools                          |
+| ----------------------- | ------------------------------ |
+| Gap tracking            | Linear, Airtable               |
+| Regulatory research     | Consensus, WebSearch, WebFetch |
+| Document review         | Lumin                          |
+| Legal document drafting | LegalZoom (NEEDS AUTH)         |
+| Contract signing        | DocuSign (FAILED)              |
+| Team coordination       | Slack, Gmail                   |
+| Technical documentation | Mermaid Chart, Context7        |
+
+### P2: Strategic Deal / Rollup (High)
+
+| Need                   | Tools                            |
+| ---------------------- | -------------------------------- |
+| Target research        | WebSearch, Consensus, LunarCrush |
+| Deal pipeline tracking | Airtable                         |
+| Engagement materials   | Gamma, Canva, Mermaid Chart      |
+| Legal review           | Lumin                            |
+| Advisor coordination   | Gmail, Calendly, Google Calendar |
+| Team coordination      | Slack, Linear                    |
+
+### P3: Platform Engineering Stabilisation (High)
+
+| Need              | Tools                   |
+| ----------------- | ----------------------- |
+| Sprint tracking   | Linear                  |
+| Code management   | GitHub (local MCP)      |
+| Bug reporting     | Jam                     |
+| Deployment        | Netlify                 |
+| Technical docs    | Context7, Mermaid Chart |
+| Team coordination | Slack                   |
+
+### P4: Capital Raising (Medium)
+
+| Need                    | Tools                            |
+| ----------------------- | -------------------------------- |
+| Investor deck creation  | Gamma                            |
+| Market intelligence     | LunarCrush, Consensus, WebSearch |
+| Investor tracking       | Airtable                         |
+| Investor communications | Gmail                            |
+| Meeting scheduling      | Calendly, Google Calendar        |
+| Meeting capture         | Granola                          |
+
+### P5: Agent Operating System Maturity (Medium)
+
+| Need                 | Tools                         |
+| -------------------- | ----------------------------- |
+| Workflow automation  | Zapier, Bash                  |
+| System configuration | Filesystem (local MCP)        |
+| Knowledge management | Memory (local MCP)            |
+| Monitoring           | Slack, Gmail, Google Calendar |
+| Deployment           | Netlify                       |
+
+---
+
+## Architecture Notes
+
+### Tool Layers
+
+```
+Layer 1 - Communication    : Slack, Gmail, Google Calendar
+Layer 2 - Execution        : Linear, Airtable, GitHub, Netlify
+Layer 3 - Intelligence     : Consensus, LunarCrush, WebSearch, Granola, Metaview
+Layer 4 - Creation         : Gamma, Canva, Figma, Mermaid Chart, tldraw
+Layer 5 - Legal/Compliance : Lumin, LegalZoom*, DocuSign*
+Layer 6 - Logistics        : Kiwi.com, lastminute.com, DirectBooker, Calendly
+Layer 7 - Automation       : Zapier (connects all layers)
+Layer 8 - Foundation       : Filesystem, Memory, Fetch, GitHub, Sequential Thinking
+```
+
+_\* = degraded or unavailable_
+
+### Configuration Files
+
+| File                           | Purpose                                                                                 |
+| ------------------------------ | --------------------------------------------------------------------------------------- |
+| `config/mcp-integrations.yaml` | Full MCP server inventory with status, use cases, and approval levels                   |
+| `config/tooling-map.yaml`      | Operational functions mapped to tools with workflows                                    |
+| `config/mcp-servers.json`      | Local MCP server configuration (filesystem, fetch, memory, github, sequential-thinking) |
+| `config/environment.yaml`      | Environment variables, rate limits, scheduling                                          |
+| `config/hiring.yaml`           | Hiring-specific configuration and approval rules                                        |
+| `config/slack-channels.yaml`   | Slack channel monitoring priorities                                                     |
+
+---
+
+_This capability map should be reviewed monthly or whenever new MCP servers are added or existing connections change status._