AI Assistants (Claude Code & GitHub Copilot) & Model Context Protocol

This document explains the Claude Code / GitHub Copilot instructions and Model Context Protocol (MCP) server configuration included in this dotfiles repository. Both tools' shareable instructions/skills content is canonically sourced from the tools repository — this dotfiles repo only stores genuinely personal preferences (.claude/settings.json, .vscode/settings.json, .vscode/mcp.json) and wires the rest up via setup-ai-agent.sh at setup time.

Claude Code

Overview

Claude Code reads CLAUDE.md (repo) and ~/.claude/CLAUDE.md (personal, always active — no opt-in setting needed, unlike Copilot). Since Claude Code has no per-file scoping, only tool-agnostic, always-relevant guidance goes in the personal file — the same "general" instructions used for Copilot, just without the applyTo frontmatter.

Installation

Automatic (during setup): ./setup/setup-osx.sh runs:

curl -fsSL https://raw.githubusercontent.com/this-is-tobi/tools/main/shell/setup-ai-agent.sh | bash -s -- -t claude -g

This creates ~/.claude/general-instructions.md and adds an @general-instructions.md import line to ~/.claude/CLAUDE.md (idempotent — safe to re-run).

Manual installation: same command, run directly.

Settings (.claude/settings.json)

Dotfiles-owned, copied to ~/.claude/settings.json during setup (this is genuinely personal preference, not shareable content, so it lives in this repo rather than the tools repo):

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "rtk hook claude" }] }
    ]
  },
  "effortLevel": "high",
  "attribution": { "commit": "" }
}

• The rtk hook claude hook is the same auto-rewrite mechanism rtk init -g installs — token-optimized shell command output, no prompt-level instructions needed.
• attribution.commit: "" disables the Co-Authored-By: Claude commit trailer.

RTK (Rust Token Killer)

rtk init -g (run automatically by the setup scripts, before .claude/settings.json is copied into place) generates ~/.claude/RTK.md and adds the @RTK.md import to ~/.claude/CLAUDE.md. See the tools repo's RTK section for details.

Custom Agents

Not installed by default. To add them:

curl -fsSL https://raw.githubusercontent.com/this-is-tobi/tools/main/shell/setup-ai-agent.sh | bash -s -- -t claude -g -a

GitHub Copilot Instructions

Overview

GitHub Copilot instructions are specialized markdown files that guide Copilot's behavior for specific tasks:

• Code generation - Language and framework best practices
• Commit messages - Conventional commit formatting
• Pull request descriptions - PR template compliance
• Code review - Review checklists and standards

Installation

The setup scripts install Copilot's personal instructions and skills via the tools repository's setup-ai-agent.sh:

Automatic (during setup):

# Instructions are installed automatically
./setup/setup-osx.sh

Manual installation:

curl -fsSL https://raw.githubusercontent.com/this-is-tobi/tools/main/shell/setup-ai-agent.sh | bash -s -- -t copilot -g -c

Instruction Files

copilot-instructions.md

Purpose: Universal development guidelines

Location: ~/.copilot/instructions/general.instructions.md

Content:

• Shell scripting best practices (error handling, quoting, etc.)
• Docker guidelines (multi-stage builds, caching, security)
• Kubernetes patterns (resource limits, health checks, labels)
• GitHub Actions workflows (reusability, security, caching)
• JavaScript/TypeScript standards (ESM, async/await, types)
• Go conventions (error handling, naming, concurrency)
• TypeScript monorepo patterns (workspace protocols, versioning)
• Performance & monitoring (observability, optimization)

Usage in VS Code:

{
  "github.copilot.chat.codeGeneration.instructions": [
    {"file": "~/.copilot/instructions/general.instructions.md"}
  ]
}

commit-message.md

Purpose: Conventional commit message generation

Location: ~/.copilot/instructions/commit-message.instructions.md

Content:

• Conventional Commits v1.0.0 specification
• Commit type definitions (feat, fix, docs, etc.)
• Scope guidelines
• Breaking change handling
• Commit message examples by type
• Multi-commit scenarios
• Best practices for atomic commits

Format enforced:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Usage in VS Code:

{
  "github.copilot.chat.commitMessageGeneration.instructions": [
    {"file": "~/.copilot/instructions/commit-message.instructions.md"}
  ]
}

Examples:

feat(api): add user authentication endpoint

fix: resolve memory leak in cache layer

docs(readme): add installation instructions

chore(deps): upgrade dependencies to latest versions

pull-request.md

Purpose: PR description best practices and template compliance

Location: ~/.copilot/instructions/pull-request.instructions.md

Content:

• PR description structure
• Template checking priority system
• Context extraction from commits
• Issue reference formatting
• Breaking change highlighting
• Examples for different PR types (features, fixes, refactors)

Template priorities:

1. .github/pull_request_template.md (highest)
2. .github/PULL_REQUEST_TEMPLATE.md
3. docs/pull_request_template.md
4. docs/PULL_REQUEST_TEMPLATE.md
5. Custom templates via comments

Usage in VS Code:

{
  "github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
    {"file": "~/.copilot/instructions/pull-request.instructions.md"}
  ]
}

code-review.md

Purpose: Expert code review guidelines

Location: ~/.copilot/instructions/code-review.instructions.md

Content:

• Priority-based review system (P0: Critical → P3: Nice-to-have)
• 10 core review areas:
  • Correctness & Logic
  • Security
  • Performance
  • Code Quality
  • Testing
  • Documentation
  • Error Handling
  • Dependencies
  • Maintainability
  • Best Practices
• Language-specific checks (JS/TS, Go, Python, Rust, Java)
• Framework-specific checks (React, Next.js, etc.)
• Infrastructure checks (Docker, Kubernetes, Terraform)
• Output format templates

Usage in VS Code:

{
  "github.copilot.chat.reviewSelection.instructions": [
    {"file": "~/.copilot/instructions/code-review.instructions.md"}
  ]
}

Review priorities:

• P0 (Critical) - Must fix before merge (security, correctness)
• P1 (Important) - Should fix (performance, errors)
• P2 (Moderate) - Consider fixing (quality, tests)
• P3 (Minor) - Nice to have (style, docs)

Using Copilot Instructions

Generating Commit Messages

1. Stage your changes: git add .
2. In VS Code, use Copilot Chat: /commit
3. Copilot generates conventional commit message
4. Review and accept or modify

Example:

You: /commit
Copilot: feat(auth): add OAuth2 authentication support

Implements OAuth2 authentication flow with support for
Google and GitHub providers. Includes token refresh logic
and secure session management.

BREAKING CHANGE: replaces existing basic auth system

Generating PR Descriptions

1. Create PR in VS Code or web
2. Use Copilot to generate description
3. Copilot checks for templates and formats appropriately

Example:

## Summary
Adds OAuth2 authentication support with Google and GitHub providers.

## Changes
- Implement OAuth2 flow
- Add token refresh mechanism
- Update authentication middleware

## Breaking Changes
⚠️ This replaces the existing basic authentication system

## Related Issues
Closes #123

Code Review

1. Select code in editor
2. Use Copilot Chat: @workspace /review
3. Copilot provides structured review with priorities

Example:

P0 (Critical):
- Missing input validation on user email (security)

P1 (Important):
- Database query in loop (performance)
- No error handling for API call

P2 (Moderate):
- Missing unit tests for new function
- Consider extracting magic number to constant

P3 (Minor):
- Add JSDoc comment
- Variable name could be more descriptive

Model Context Protocol (MCP)

Overview

MCP provides standardized access to external tools and data sources for AI assistants. This dotfiles repo configures the same set of servers for both Claude Code (added via claude mcp add ... -s user in the setup scripts) and VS Code Copilot (.vscode/mcp.json) — github is the one exception, since it authenticates via the VS Code Copilot session and has no equivalent for Claude Code.

Configured Servers

GitHub MCP Server

Type: HTTP

Purpose: GitHub API integration (repos, PRs, issues, code search, Actions)

Configuration (.vscode/mcp.json):

{
  "github": {
    "type": "http",
    "url": "https://api.githubcopilot.com/mcp/"
  }
}

No setup required - uses your VS Code GitHub authentication. Copilot (VS Code) only — Claude Code has its own native GitHub integration via the gh CLI instead.

Context7 MCP Server

Type: HTTP

Purpose: Up-to-date library and framework documentation

Configuration (.vscode/mcp.json):

{
  "context7": {
    "type": "http",
    "url": "https://mcp.context7.com/mcp",
    "headers": {
      "CONTEXT7_API_KEY": "${env:CONTEXT7_API_KEY}"
    }
  }
}

Claude Code setup (done automatically by the setup scripts):

claude mcp add --transport http context7 https://mcp.context7.com/mcp -H "CONTEXT7_API_KEY: ${CONTEXT7_API_KEY}" -s user

Setup required:

1. Get an API key at context7.com
2. Add to ~/.config/dotfiles/env.sh:

export CONTEXT7_API_KEY="your_api_key_here"

3. Restart terminal, VS Code, and any running Claude Code sessions

Kubernetes MCP Server

Type: stdio (npx)

Purpose: Kubernetes cluster management (pods, services, deployments, logs, events)

Configuration (.vscode/mcp.json):

{
  "kubernetes": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "kubernetes-mcp-server@latest"]
  }
}

Claude Code setup:

claude mcp add kubernetes -s user -- npx -y kubernetes-mcp-server@latest

Setup required: ~/.kube/config must exist, be valid, and point at a reachable cluster.

ArgoCD MCP Server

Type: stdio (npx)

Purpose: List/sync/inspect ArgoCD applications

Configuration (.vscode/mcp.json):

{
  "argocd": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "argocd-mcp@latest", "stdio"],
    "env": {
      "ARGOCD_BASE_URL": "https://gitops.ohmlab.fr",
      "ARGOCD_API_TOKEN": "${env:ARGOCD_API_TOKEN}"
    }
  }
}

Claude Code setup:

claude mcp add argocd -s user -e ARGOCD_BASE_URL=https://gitops.ohmlab.fr -e ARGOCD_API_TOKEN="${ARGOCD_API_TOKEN}" -- npx -y argocd-mcp@latest stdio

Setup required: an ArgoCD API token (Settings > Accounts > Generate Token) exported as ARGOCD_API_TOKEN.

Playwright MCP Server

Type: stdio (npx)

Purpose: Browser automation (navigate, click, screenshot, fill forms)

Configuration (.vscode/mcp.json, registered as microsoft/playwright-mcp):

{
  "microsoft/playwright-mcp": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest"]
  }
}

Claude Code setup (registered as playwright):

claude mcp add playwright -s user -- npx -y @playwright/mcp@latest

Setup required: none beyond Node/npx being available.

Adding Custom MCP Servers

Finding MCP Servers

Browse available servers:

• Awesome MCP Servers
• MCP Registry
• Community repositories

Adding a Server

1. Edit .vscode/mcp.json:

{
  "my-server": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/server.js"]
  }
}

2. Server types:

stdio (Standard Input/Output):

{
  "type": "stdio",
  "command": "node",
  "args": ["server.js"]
}

http (HTTP Endpoint):

{
  "type": "http",
  "serverUrl": "https://api.example.com/mcp"
}

sse (Server-Sent Events):

{
  "type": "sse",
  "serverUrl": "https://api.example.com/sse",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

docker (Docker Container):

{
  "type": "docker",
  "args": {
    "image": "my-mcp-server:latest",
    "volumes": ["/host/path:/container/path:ro"]
  }
}

3. Restart VS Code to load new server

Troubleshooting

Copilot Instructions Not Applied

Check file paths:

ls -la ~/.copilot/instructions/

Verify VS Code settings:

code ~/.vscode/settings.json
# Ensure paths use absolute notation starting with ~

Reload instructions:

1. Restart VS Code
2. Or reload window: Cmd+Shift+P → "Reload Window"

MCP Server Connection Failed

Check server status:

1. Cmd+Shift+P → "MCP: Show Server Status"
2. Review error messages

Common issues:

Missing environment variables:

# Verify in terminal
echo $CONTEXT7_API_KEY

# Add to env.sh if missing
vim ~/.config/dotfiles/env.sh

Docker not running:

# Start Docker Desktop
open -a Docker

# Verify
docker ps

Invalid Kubernetes config:

# Test cluster access
kubectl cluster-info

# Update config if needed

Copilot Not Using MCP Servers

Explicitly mention the server:

You: Using GitHub MCP, what's the status of PR #42?

Check Copilot settings:

• Ensure Copilot is enabled
• Verify MCP integration is active
• Check network connectivity

Best Practices

Instruction Files

• Keep instructions concise and actionable
• Update instructions as practices evolve
• Use project-specific instructions when needed
• Share instructions with team

MCP Servers

• Only enable servers you actively use
• Use read-only volumes for security
• Rotate API keys regularly
• Monitor server performance
• Keep Docker images updated

Security

• Never commit API keys to git
• Use environment variables for secrets
• Review MCP server permissions
• Use minimal necessary scopes

Further Reading

• Claude Code Documentation
• GitHub Copilot Documentation
• Model Context Protocol Specification
• Conventional Commits
• Tools Repository