Server Context File for LLM @ Referencing

Overview

The .mcp-server-context.md file is a living document that bridges the gap between the server's internal memory systems (stored in /tmp as JSON) and your LLM's working context. By @ mentioning this file, LLMs instantly gain awareness of:

Available tools and capabilities
Recent activity and intents
Memory entities and relationships
Discovered patterns
Active recommendations
Knowledge gaps

What Problem Does This Solve?

Before: Your MCP server has powerful memory systems (KnowledgeGraphManager, MemoryEntityManager, ConversationMemoryManager) but they're invisible to the LLM unless explicitly queried.

After: LLMs can @.mcp-server-context.md to instantly understand:

What's been happening recently
What architectural decisions exist
What patterns have been discovered
What the server recommends doing next

How It Works

Auto-Generated Content

The file is populated from three memory systems:

Knowledge Graph → Active intents, tool usage, score trends
Memory Entities → Architectural decisions, relationships, patterns
Conversation Memory → Active sessions, turn count, context

Real-Time Updates

The context file updates automatically:

✅ After every tool execution
✅ When memory entities change
✅ When conversation sessions start/end
✅ On server restart
✅ On manual request via MCP tool

Usage Examples

Starting a New Conversation

@.mcp-server-context.md I'm new to this project. What architectural
decisions have been made?

LLM Response: "Based on the context file, I can see we have 12 architectural decisions documented, with 3 active intents. The most recent decision was about..."

Resuming Work

@.mcp-server-context.md What was I working on? Show me the active intents

LLM Response: "Looking at the context, you have 2 active intents:

Database migration strategy (started 2h ago)
API gateway selection (started yesterday)"

Understanding Patterns

@.mcp-server-context.md What patterns have we discovered in our architecture?

LLM Response: "The context shows 3 discovered patterns:

Microservices pattern (85% confidence)
Event-driven architecture (72% confidence)
CQRS pattern (68% confidence)"

Checking Progress

@.mcp-server-context.md How has our architecture score changed?

LLM Response: "Your current project score is 87/100, up 12 points from the initial baseline. The top improvements came from..."

Integration Steps

1. Register the Tool (in `src/index.ts`)

import { getServerContext, getServerContextMetadata } from './tools/get-server-context-tool.js';

// In your tool registration:
case 'get_server_context':
  return await getServerContext(
    args as GetServerContextArgs,
    {
      kgManager: this.kgManager,
      memoryManager: this.memoryManager,
      conversationManager: this.conversationMemoryManager,
    }
  );

2. Add to Tool List

{
  name: 'get_server_context',
  description: 'Generate a comprehensive context file showing the server\'s current state',
  inputSchema: getServerContextMetadata.inputSchema,
}

3. Auto-Update on Tool Execution

Add this hook to your tool execution handler:

// After successful tool execution
async function afterToolExecution() {
  const generator = new ServerContextGenerator();
  await generator.writeContextFile(kgManager, memoryManager, conversationManager);
}

4. Update on Server Startup

In your McpAdrAnalysisServer constructor:

async initialize() {
  // ... existing initialization ...

  // Generate initial context file
  const generator = new ServerContextGenerator();
  await generator.writeContextFile(
    this.kgManager,
    this.memoryManager,
    this.conversationMemoryManager
  );

  this.logger.info('Server context file created', 'McpAdrAnalysisServer');
}

File Structure

# MCP Server Context & Memory

## 🎯 Server Quick Reference

- Server name, purpose, paths
- Available tools (quick reference list)

## 🧠 Memory & Knowledge Graph Status

- Active intents (last 5)
- Memory entities breakdown
- Conversation context

## 📊 Recent Analytics

- Tool usage (most used)
- Score trends
- Top impacting intents

## 🔍 Discovered Patterns

- Architectural patterns with confidence
- Suggested relationships

## 🎯 Recommendations for This Session

- Next actions
- Knowledge gaps
- Optimization opportunities

## 📝 How to Use This Context

- Usage examples

## 🔄 Context Refresh

- Auto-update triggers
- Manual refresh instructions

Benefits

1. Instant Context Awareness

LLMs don't need to query multiple tools to understand the server state - just @ the file.

2. Conversation Continuity

When resuming work, @ the file to recover context from previous sessions.

3. Pattern Recognition

LLMs can see discovered patterns and make better architectural recommendations.

4. Guided Workflows

The recommendations section guides LLMs toward high-value actions.

5. Memory Bridge

Connects JSON-based memory systems to human-readable markdown that LLMs can process.

Example Context File

# MCP Server Context & Memory

> **Last Updated**: 2025-01-12T15:30:00Z

## 🎯 Server Quick Reference

**Name**: mcp-adr-analysis-server
**Project Path**: `/home/user/my-project`
**ADR Directory**: `docs/adrs`

### Available Tools

1. **adr_suggestion** - Suggest new ADRs
2. **smart_score** - Score architecture (0-100)
3. **deployment_readiness** - Validate deployment
   ...

## 🧠 Memory & Knowledge Graph Status

### Active Intents

**Total**: 15 | **Active**: 2 | **Completed**: 13

**Recent Intents**:

- **Implement database migration strategy** - executing - 2h ago
- **Select API gateway solution** - planning - 1d ago
  ...

### Memory Entities

**Total Entities**: 28
**Relationships**: 45
**Average Confidence**: 87%

**Entity Breakdown**:

- Architectural Decisions: 12
- Technical Decisions: 8
- Observations: 5
- Patterns: 3

## 📊 Recent Analytics

### Tool Usage

1. **adr_suggestion**: 34 calls
2. **smart_score**: 28 calls
3. **deployment_readiness**: 15 calls

### Score Trends

- **Current Score**: 87/100
- **Improvement**: +12 points
  ...

Troubleshooting

File Not Updating

Check: Is the tool execution hook in place?

// After tool execution
await generator.writeContextFile(...);

File Missing on Startup

Check: Is the initialization call present?

// In server constructor
await generator.writeContextFile(...);

Outdated Information

Solution: Manually trigger update:

Use MCP tool: get_server_context with writeToFile: true

Advanced Configuration

Custom Output Path

await generator.writeContextFile(
  kgManager,
  memoryManager,
  conversationManager,
  '/custom/path/context.md'
);

Limit Recent Items

await generator.generateContext(kgManager, memoryManager, conversationManager, {
  maxRecentItems: 10,
});

Disable Detailed Info

await generator.generateContext(kgManager, memoryManager, conversationManager, {
  includeDetailed: false,
});

💡 Pro Tip: Add .mcp-server-context.md to your .gitignore since it's auto-generated and changes frequently. But do commit it once with sample data so other developers understand what it's for!

Overview​

What Problem Does This Solve?​

How It Works​

Auto-Generated Content​

Real-Time Updates​

Usage Examples​

Starting a New Conversation​

Resuming Work​

Understanding Patterns​

Checking Progress​

Integration Steps​

1. Register the Tool (in src/index.ts)​

2. Add to Tool List​

3. Auto-Update on Tool Execution​

4. Update on Server Startup​

File Structure​

Benefits​

1. Instant Context Awareness​

2. Conversation Continuity​

3. Pattern Recognition​

4. Guided Workflows​

5. Memory Bridge​

Example Context File​

Troubleshooting​

File Not Updating​

File Missing on Startup​

Outdated Information​

Advanced Configuration​

Custom Output Path​

Limit Recent Items​

Disable Detailed Info​

Related Documentation​