FoundryVTT/.claude/agents/MCP_USAGE_TEMPLATES.md

# MCP Usage Templates for Agents & Commands

> **Purpose**: Copy-paste templates for adding MCP server usage sections to agent and command files
> **For complete MCP documentation**: See [../../MCP_SERVERS_GUIDE.md](../../MCP_SERVERS_GUIDE.md)
>
> **This is a TEMPLATE file** - Use these examples when creating or updating agents and commands

---

## Standard MCP Section for Agents/Commands

```markdown
## MCP Server Usage

### Serena MCP

**Code Navigation** (Understanding & modifying code):
- `find_symbol` - Locate code symbols by name/pattern
- `find_referencing_symbols` - Find all symbol references
- `get_symbols_overview` - Get file structure overview
- `search_for_pattern` - Search for code patterns
- `rename_symbol` - Safely rename across codebase
- `replace_symbol_body` - Replace function/class body
- `insert_after_symbol` / `insert_before_symbol` - Add code

**Persistent Memory** (Long-term project knowledge):
- `write_memory` - Store persistent project information
- `read_memory` - Recall stored information
- `list_memories` - Browse all memories
- `delete_memory` - Remove outdated information

**Use Serena Memory For**:
- ✅ Architectural Decision Records (ADRs)
- ✅ Code review findings and summaries
- ✅ Lessons learned from implementations
- ✅ Project-specific patterns discovered
- ✅ Technical debt registry
- ✅ Security audit results
- ✅ Performance optimization notes
- ✅ Migration documentation
- ✅ Incident post-mortems

**Files stored in**: `.serena/memories/` (persistent across sessions)

### Memory MCP (Knowledge Graph)

**Temporary Context** (Current session only):
- `create_entities` - Create entities (Features, Classes, Services, etc.)
- `create_relations` - Define relationships between entities
- `add_observations` - Add details/observations to entities
- `search_nodes` - Search the knowledge graph
- `read_graph` - View entire graph state
- `open_nodes` - Retrieve specific entities

**Use Memory Graph For**:
- ✅ Current conversation context
- ✅ Temporary analysis during current task
- ✅ Entity relationships in current work
- ✅ Cross-file refactoring state (temporary)
- ✅ Session-specific tracking

**Storage**: In-memory only, **cleared after session ends**

### Context7 MCP

- `resolve-library-id` - Find library identifier
- `get-library-docs` - Get current framework/library documentation

### Other MCP Servers

- **fetch**: Web content retrieval
- **playwright**: Browser automation
- **windows-mcp**: Windows desktop automation
- **sequential-thinking**: Complex reasoning
```

---

## Usage Examples by Agent Type

### Architect Agent

```markdown
## MCP Server Usage

### Serena MCP
**Code Analysis**:
- Use `get_symbols_overview` to understand current architecture
- Use `find_symbol` to locate key components
- Use `search_for_pattern` to identify architectural patterns

**Decision Recording**:
- Use `write_memory` to store ADRs:
  - Memory: "adr-001-microservices-architecture"
  - Memory: "adr-002-database-choice-postgresql"
  - Memory: "adr-003-authentication-strategy"
- Use `read_memory` to review past architectural decisions
- Use `list_memories` to see all ADRs

### Memory MCP
**Current Design**:
- Use `create_entities` for components being designed
- Use `create_relations` to model dependencies
- Use `add_observations` to document design rationale

**Note**: After design is finalized, store in Serena memory as ADR.
```

### Code Reviewer Agent

```markdown
## MCP Server Usage

### Serena MCP
**Code Analysis**:
- Use `find_symbol` to locate reviewed code
- Use `find_referencing_symbols` for impact analysis
- Use `get_symbols_overview` for structure understanding

**Review Recording**:
- Use `write_memory` to store review findings:
  - Memory: "code-review-2024-10-payment-service"
  - Memory: "code-review-2024-10-auth-refactor"
- Use `read_memory` to check past review patterns
- Use `list_memories` to see review history

### Memory MCP
**Current Review**:
- Use `create_entities` for issues found (Critical, Warning, Suggestion)
- Use `create_relations` to link issues to code locations
- Use `add_observations` to add fix recommendations

**Note**: Summary stored in Serena memory after review completes.
```

### Security Analyst Agent

```markdown
## MCP Server Usage

### Serena MCP
**Code Analysis**:
- Use `find_symbol` to locate security-sensitive code
- Use `search_for_pattern` to find potential vulnerabilities
- Use `find_referencing_symbols` to trace data flow

**Security Recording**:
- Use `write_memory` to store audit results:
  - Memory: "security-audit-2024-10-full-scan"
  - Memory: "vulnerability-sql-injection-fixed"
  - Memory: "security-pattern-input-validation"
- Use `read_memory` to check known vulnerabilities
- Use `list_memories` to review security history

### Memory MCP
**Current Audit**:
- Use `create_entities` for vulnerabilities found
- Use `create_relations` to link vulnerabilities to affected code
- Use `add_observations` to document severity and remediation

**Note**: Audit summary stored in Serena memory for future reference.
```

### Test Engineer Agent

```markdown
## MCP Server Usage

### Serena MCP
**Code Analysis**:
- Use `find_symbol` to locate code to test
- Use `find_referencing_symbols` to understand dependencies
- Use `get_symbols_overview` to plan test structure

**Testing Knowledge**:
- Use `write_memory` to store test patterns:
  - Memory: "test-pattern-async-handlers"
  - Memory: "test-pattern-database-mocking"
  - Memory: "lesson-flaky-test-prevention"
- Use `read_memory` to recall test strategies
- Use `list_memories` to review testing conventions

### Memory MCP
**Current Test Generation**:
- Use `create_entities` for test cases being generated
- Use `create_relations` to link tests to code under test
- Use `add_observations` to document test rationale

**Note**: Test patterns stored in Serena memory for reuse.
```

---

## Command Examples

### /implement Command

```markdown
## MCP Server Usage

### Serena MCP
**Code Navigation**:
- `find_symbol` - Locate existing patterns to follow
- `find_referencing_symbols` - Understand dependencies
- `rename_symbol` - Refactor safely during implementation

**Knowledge Capture**:
- `write_memory` - Store implementation lessons:
  - "lesson-payment-integration-stripe"
  - "pattern-error-handling-async"
- `read_memory` - Recall similar implementations
- `list_memories` - Check for existing patterns

### Memory MCP
**Implementation Tracking**:
- `create_entities` - Track features/services being implemented
- `create_relations` - Model integration points
- `add_observations` - Document decisions made

### Context7 MCP
- `get-library-docs` - Current framework documentation
```

### /analyze Command

```markdown
## MCP Server Usage

### Serena MCP
**Code Analysis**:
- `get_symbols_overview` - Understand structure
- `find_symbol` - Locate complex code
- `search_for_pattern` - Find duplicates or patterns

**Analysis Recording**:
- `write_memory` - Store analysis findings:
  - "analysis-2024-10-technical-debt"
  - "analysis-complexity-hotspots"
- `read_memory` - Compare to past analyses
- `list_memories` - Track analysis history

### Memory MCP
**Current Analysis**:
- `create_entities` - Track files/functions being analyzed
- `create_relations` - Model dependencies
- `add_observations` - Document complexity metrics
```

---

## Do's and Don'ts

### ✅ DO

**Serena Memory**:
- ✅ Store ADRs that need to persist
- ✅ Record code review summaries
- ✅ Save lessons learned
- ✅ Document project patterns
- ✅ Track technical debt
- ✅ Store security findings
- ✅ Keep performance notes
- ✅ Remember migration steps

**Memory Graph**:
- ✅ Build temporary context for current task
- ✅ Track entities during analysis
- ✅ Model relationships while designing
- ✅ Store session-specific state

### ❌ DON'T

**Serena Memory**:
- ❌ Store temporary analysis state
- ❌ Use for current conversation context
- ❌ Store what's only needed right now

**Memory Graph**:
- ❌ Try to persist long-term knowledge
- ❌ Store ADRs or lessons learned
- ❌ Save project patterns here
- ❌ Expect it to survive session end

---

## Quick Decision Tree

**Question**: Should this information exist next week?
- **YES** → Use Serena `write_memory`
- **NO** → Use Memory graph

**Question**: Am I navigating or editing code?
- **YES** → Use Serena code functions

**Question**: Am I building temporary context for current task?
- **YES** → Use Memory graph

**Question**: Do I need current library documentation?
- **YES** → Use Context7

---

## File Naming Conventions (Serena Memories)

### ADRs (Architectural Decision Records)
```
adr-001-database-choice-postgresql
adr-002-authentication-jwt-strategy
adr-003-api-versioning-approach
```

### Code Reviews
```
code-review-2024-10-15-payment-service
code-review-2025-10-20-auth-refactor
```

### Lessons Learned
```
lesson-async-error-handling
lesson-database-connection-pooling
lesson-api-rate-limiting
```

### Patterns
```
pattern-repository-implementation
pattern-error-response-format
pattern-logging-strategy
```

### Technical Debt
```
debt-legacy-api-authentication
debt-payment-service-refactor-needed
```

### Security
```
security-audit-2024-10-full
security-vulnerability-xss-fixed
security-pattern-input-validation
```

### Performance
```
performance-optimization-query-caching
performance-analysis-api-endpoints
```

---

**Version**: 2.0.0
**Last Updated**: 2025-10-20
**Location**: `.claude/agents/MCP_USAGE_TEMPLATES.md`
**Use this**: As copy-paste template when creating/updating agents and commands
**Complete docs**: [../../MCP_SERVERS_GUIDE.md](../../MCP_SERVERS_GUIDE.md)