LLM Configuration Guide: Using the Server Context File

Overview

The .mcp-server-context.md file is your project's living memory system. It automatically tracks:

📝 All ADRs and architectural decisions
📊 Project score trends and improvements
🔍 Discovered patterns and relationships
🎯 Recent activity and recommendations
🧠 Memory entities and knowledge graph

This guide shows you how to configure different LLMs to always use this context file for maximum effectiveness.

Why This Matters

Without Context File:

User: "Create an ADR for API authentication"
LLM: *Creates generic JWT-based auth ADR*

With Context File:

User: "@.mcp-server-context.md Create an ADR for API authentication"
LLM: *Sees you already use OAuth2 for other services*
     *References your existing security patterns*
     *Aligns with ADR-005's security principles*
     *Creates consistent, project-specific ADR*

Configuration by LLM

🤖 Google Gemini

Gemini has shorter context windows, so the context file is critical for continuity.

Option 1: System Instructions (Recommended)

When creating a Gemini app or using the API:

import google.generativeai as genai

# Configure with system instructions
model = genai.GenerativeModel(
    model_name="gemini-1.5-pro",
    system_instruction="""
You are working with the MCP ADR Analysis Server for architectural decisions.

CRITICAL WORKFLOW - ALWAYS FOLLOW:
1. BEFORE any ADR operation: Read @.mcp-server-context.md
2. USE the context to understand:
   - Previous architectural decisions
   - Discovered patterns and relationships
   - Current project score and trends
   - Recent changes and recommendations
3. AFTER completing work: Call get_server_context tool to update the file
4. REFERENCE specific ADRs and patterns from context in your responses

The context file ensures continuity across sessions and prevents conflicting decisions.
"""
)

Option 2: Claude Desktop with Gemini MCP Client

If using Claude Desktop as your MCP client but want Gemini:

~/.config/claude-desktop/config.json:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "node",
      "args": ["/path/to/mcp-adr-analysis-server/dist/src/index.js"],
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "ADR_DIRECTORY": "docs/adrs",
        "AI_MODEL": "google/gemini-1.5-pro",
        "OPENROUTER_API_KEY": "your-openrouter-key"
      }
    }
  },
  "systemPrompt": "Before ANY architectural work, read @.mcp-server-context.md for project history and patterns. After significant changes, call get_server_context to update it."
}

Option 3: Manual Prompting

For each session, start with:

@.mcp-server-context.md

I'm working on [task]. Please:
1. Review the context file above
2. Identify relevant ADRs and patterns
3. Ensure my work aligns with existing decisions
4. Call get_server_context when done to update the file

🔵 Claude (Anthropic)

Claude Code and Claude Desktop natively support MCP with good context retention.

Claude Desktop Configuration

~/.config/claude-desktop/config.json (macOS/Linux) %APPDATA%/Claude/config.json (Windows)

{
  "mcpServers": {
    "adr-analysis": {
      "command": "node",
      "args": ["/path/to/mcp-adr-analysis-server/dist/src/index.js"],
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "ADR_DIRECTORY": "docs/adrs"
      }
    }
  },
  "globalSettings": {
    "beforeAnyArchitecturalWork": {
      "action": "READ_FILE",
      "file": ".mcp-server-context.md",
      "reason": "Maintain consistency with previous decisions and patterns"
    }
  }
}

Custom Instructions (Projects Feature)

If your Claude account has Projects:

# Project: [Your Project Name]

## Context File Protocol

ALWAYS follow this workflow:

1. **Before starting any architectural work:**
   - Use: `@.mcp-server-context.md`
   - Review: Recent ADRs, patterns, and project score

2. **During work:**
   - Reference specific ADRs from context
   - Align with discovered patterns
   - Maintain consistency with previous decisions

3. **After completing work:**
   - Call `get_server_context` tool
   - Verify context file updated
   - Note new patterns discovered

## Why This Matters

The context file prevents conflicting decisions and maintains architectural integrity across sessions.

🟢 OpenAI GPT-4 / ChatGPT

GPT-4 has good context retention but benefits from explicit reminders.

Option 1: Custom GPT with Instructions

Create a Custom GPT with these instructions:

# MCP ADR Analysis Assistant

You are an architectural decision assistant using the MCP ADR Analysis Server.

## Core Protocol

**BEFORE every architectural task:**
1. Request to read .mcp-server-context.md
2. Review recent ADRs and patterns
3. Check current project score and trends

**DURING task execution:**
- Reference specific ADRs by number (e.g., "As per ADR-005...")
- Align with discovered patterns
- Maintain consistency with previous decisions

**AFTER completing significant work:**
- Call get_server_context tool
- Summarize updates made to context
- Highlight new patterns discovered

## Key Principles
- Never make architectural decisions without context
- Always reference previous ADRs when relevant
- Maintain architectural consistency across sessions
- Update context after substantial changes

## When to Use Context File
✅ Creating new ADRs
✅ Validating existing ADRs
✅ Reviewing project architecture
✅ Making deployment decisions
✅ Analyzing code against ADRs

Option 2: API Integration

const OpenAI = require('openai');

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function chatWithContext(userMessage) {
  const messages = [
    {
      role: 'system',
      content: `You are working with the MCP ADR Analysis Server.

WORKFLOW:
1. Before architectural decisions: Read @.mcp-server-context.md
2. Reference previous ADRs and patterns from context
3. After work: Call get_server_context to update

The context file is critical for consistency across sessions.`,
    },
    {
      role: 'user',
      content: `@.mcp-server-context.md\n\n${userMessage}`,
    },
  ];

  const response = await openai.chat.completions.create({
    model: 'gpt-4-turbo-preview',
    messages: messages,
  });

  return response.choices[0].message.content;
}

Universal Workflow Template

Regardless of your LLM, use this workflow:

📥 START OF SESSION

@.mcp-server-context.md

What were we working on? Show me:
- Active intents
- Recent ADRs created/modified
- Current project score
- Any recommended next actions

🔨 DURING WORK

@.mcp-server-context.md

I need to [task]. Please:
1. Review relevant ADRs from context
2. Check for related patterns
3. Ensure alignment with previous decisions
4. Proceed with the task

✅ END OF SESSION

Please call the get_server_context tool to update .mcp-server-context.md with:
- Work completed this session
- New patterns discovered
- ADRs created/modified
- Recommendations for next session

Advanced: Automated Context Reading

Pre-Commit Hook

Automatically update context before commits:

.git/hooks/pre-commit:

#!/bin/bash

# Update context file before commit
echo "Updating .mcp-server-context.md..."

# Call MCP server to refresh context
node /path/to/mcp-adr-analysis-server/dist/src/index.js \
  --tool get_server_context

# Add to staging if changed
git add .mcp-server-context.md

echo "✅ Context file updated"

CI/CD Integration

GitHub Actions (.github/workflows/update-context.yml):

name: Update Context File

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  update-context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install MCP Server
        run: npm install -g mcp-adr-analysis-server

      - name: Update Context File
        run: |
          npx mcp-server --tool get_server_context

      - name: Commit Updated Context
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add .mcp-server-context.md
          git commit -m "chore: update server context file [skip ci]" || true
          git push

Troubleshooting

Context File Not Updating

Problem: Context file shows old data

Solutions:

Manually refresh: Call get_server_context tool
Restart MCP server
Check file permissions on .mcp-server-context.md
Verify PROJECT_PATH environment variable

LLM Not Reading Context File

Problem: LLM creates inconsistent ADRs

Solutions:

Explicitly reference the file: @.mcp-server-context.md
Check system prompts are configured correctly
Use stronger language: "REQUIRED: Read .mcp-server-context.md first"
Test with a direct question: "What does @.mcp-server-context.md say about our current architecture?"

Context File Too Large

Problem: Context file exceeds LLM token limits

Solutions:

The file auto-limits recent items (default: 5)

Focus on specific sections:

@.mcp-server-context.md show me just:
- Recent Intents (last 3)
- Memory Entities (ADR-related only)

Use maxRecentItems parameter in get_server_context:

{
  "tool": "get_server_context",
  "arguments": {
    "maxRecentItems": 3
  }
}

Best Practices

✅ DO

Always read context before architectural decisions
Update context after significant changes
Reference specific ADRs by number when relevant
Check patterns for consistency
Track progress via project score

❌ DON'T

Skip reading context for "small" changes
Make conflicting decisions without checking existing ADRs
Forget to update context after creating ADRs
Ignore patterns and recommendations
Let context file get stale

Real-World Example

Bad: Without Context File

User: "Create an ADR for caching strategy"
LLM: "I'll create a Redis caching ADR..."
       *Creates ADR-042*

Reality: Project already uses Memcached (ADR-015)
         Conflicts with ADR-023 infrastructure decisions
         Adds unnecessary complexity

Good: With Context File

User: "@.mcp-server-context.md Create an ADR for caching strategy"
LLM: "I see from the context:
      - ADR-015 established Memcached as standard cache
      - ADR-023 requires infrastructure consistency
      - Pattern: Prefer extending existing solutions

      I'll create ADR-042 extending Memcached for the new use case..."

      *Creates consistent ADR*
      *Calls get_server_context to update*

Summary

The .mcp-server-context.md file transforms your LLM from a stateless assistant into a project-aware architect.

Key Points:

📖 Always read before architectural work
✍️ Always update after significant changes
🔗 Reference specific ADRs from context
🎯 Follow patterns for consistency
🚀 Track progress via project scores

Configure your LLM to use this workflow, and watch your architectural decision quality improve dramatically!

Next Steps:

Configure your LLM using the examples above
Test by asking: "What does @.mcp-server-context.md show?"
Create your first context-aware ADR
Call get_server_context to verify updates

Need Help?

See: Server Context File Guide
Tool: get_server_context - Refresh context manually
Issue: Report Configuration Problems

Overview​

Why This Matters​

Configuration by LLM​

🤖 Google Gemini​

Option 1: System Instructions (Recommended)​

Option 2: Claude Desktop with Gemini MCP Client​

Option 3: Manual Prompting​

🔵 Claude (Anthropic)​

Claude Desktop Configuration​

Custom Instructions (Projects Feature)​

🟢 OpenAI GPT-4 / ChatGPT​

Option 1: Custom GPT with Instructions​

Option 2: API Integration​

Universal Workflow Template​

📥 START OF SESSION​

🔨 DURING WORK​

✅ END OF SESSION​

Advanced: Automated Context Reading​

Pre-Commit Hook​

CI/CD Integration​

Troubleshooting​

Context File Not Updating​

LLM Not Reading Context File​

Context File Too Large​

Best Practices​

✅ DO​

❌ DON'T​

Real-World Example​

Bad: Without Context File​

Good: With Context File​

Summary​

Overview

Why This Matters

Configuration by LLM

🤖 Google Gemini

Option 1: System Instructions (Recommended)

Option 2: Claude Desktop with Gemini MCP Client

Option 3: Manual Prompting

🔵 Claude (Anthropic)

Claude Desktop Configuration

Custom Instructions (Projects Feature)

🟢 OpenAI GPT-4 / ChatGPT

Option 1: Custom GPT with Instructions

Option 2: API Integration

Universal Workflow Template

📥 START OF SESSION

🔨 DURING WORK

✅ END OF SESSION

Advanced: Automated Context Reading

Pre-Commit Hook

CI/CD Integration

Troubleshooting

Context File Not Updating

LLM Not Reading Context File

Context File Too Large

Best Practices

✅ DO

❌ DON'T

Real-World Example

Bad: Without Context File

Good: With Context File

Summary