Martin-Atrin/pcm-mcp

PCM MCP Server

Progressive Context Mapping (PCM) as a Model Context Protocol (MCP) server. Transform any codebase into an intelligent, hierarchical documentation system that provides perfect context for LLM-assisted development.

🎯 What is PCM?

PCM creates context bubbles around any point in your codebase by:

• 📁 Scanning projects to identify documentation needs
• 🔍 Generating LLM-ready analysis prompts
• 📝 Creating structured .pcm.md files alongside source code
• 🌳 Building comprehensive context trees in PCM.md
• 🎯 Providing hierarchical context on-demand

🚀 Quick Start

Installation

# Global installation (recommended)
npm install -g pcm-mcp-server

# Or local to project
npm install pcm-mcp-server

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pcm": {
      "command": "pcm-mcp-server"
    }
  }
}

Alternative paths if global install doesn't work:

{
  "mcpServers": {
    "pcm": {
      "command": "node",
      "args": ["/usr/local/lib/node_modules/pcm-mcp-server/dist/index.js"]
    }
  }
}

Other MCP Clients

Works with any MCP-compatible client:

• Cline (VS Code)
• Cursor
• Claude Desktop
• Custom MCP clients

🛠️ Available Tools

💡 Key Feature: Context Generation

The pcm-generate-context tool is the star feature:

pcm-generate-context({ 
  targetPath: "/project/src/components/Button.tsx",
  includeSource: true
})

Returns intelligent context:

• 🎯 Target: Documentation + source for your file
• ⬆️ Parents: Context from directories above (architecture)
• ⬇️ Children: Context from files/components below (dependencies)

Perfect for:

• Understanding unfamiliar code
• Making targeted changes
• Code reviews
• Debugging
• Refactoring

📖 Complete Workflow

1. Initial Setup

// See what needs documentation
pcm-scan({ projectPath: "/path/to/project" })

// Create placeholder files
pcm-ingest({ projectPath: "/path/to/project", batch: 10 })

2. Documentation Phase

// Get analysis prompts
pcm-analyze({ projectPath: "/path/to/project", batch: 5 })

// Write documentation (after using prompts with LLM)
pcm-write({ 
  targetPath: "/path/to/project/src/index.js",
  content: "# Index Module\n\nMain entry point for the application..."
})

3. Context Generation

// Generate context tree
pcm-update({ projectPath: "/path/to/project" })

// Get focused context for development
pcm-generate-context({ 
  targetPath: "/path/to/project/src/components/Button.tsx",
  includeSource: true
})

🏗️ How PCM Works

File Structure

your-project/
├── src/
│   ├── src.pcm.md              # Directory documentation
│   ├── components/
│   │   ├── components.pcm.md   # Directory documentation  
│   │   ├── Button.tsx
│   │   ├── Button.pcm.md       # File documentation
│   │   └── Modal.tsx
│   └── utils/
└── PCM.md                      # Root context tree

Context Hierarchy

When you call pcm-generate-context on Button.tsx:

🏗️  your-project/           # Root context
  └── 📁 src/                # Parent context  
    └── 📁 components/       # Parent context
      ├── 🎯 Button.tsx      # Target + source
      └── 📄 Modal.tsx       # Child context

⚙️ Configuration

PCM looks for pcm.config.json in the pcm-tool/ directory:

{
  "ignoreDirectories": [".git", "node_modules", ".venv", "__pycache__"],
  "criticalExtensions": [".js", ".py", ".json", ".ts", ".tsx", ".jsx"],
  "criticalFiles": ["Dockerfile", "package.json", "README.md"],
  "minFileSize": 20,
  "placeholderText": "[NEEDS_ANALYSIS]"
}

🎨 Example Output

Context Generation Output

# Context Map for Button.tsx

## Target Context
**Path:** src/components/Button.tsx
**Type:** File

React button component with variant support and accessibility features...

### Source Content
\`\`\`typescript
import React from 'react';
interface ButtonProps {
  variant: 'primary' | 'secondary';
  // ...
}
\`\`\`

## Parent Context (Above)
### src
Main source directory containing all application code...

### components  
UI component library with reusable React components...

## Child Context (Below)
### Button.test.tsx
Test suite for Button component...

### Button.stories.tsx
Storybook stories for Button component...

🔧 Development

Local Development

git clone https://github.com/Martin-Atrin/pcm-mcp.git
cd pcm-mcp
npm install
npm run build
npm run dev

Testing

npm test
npm run lint

Building

npm run build
npm run pack-test  # Test package contents

🤝 Integration with Existing Tools

Legacy PCM Tool Compatibility

This MCP server works alongside the existing Node.js/Python PCM tool:

# Legacy server (still works)
node pcm-tool/pcm-server.js &

# Legacy CLI (still works)  
python3 pcm-tool/pcm_handler.py ingest /path/to/project

API Equivalents

🎯 Use Cases

🔍 Code Exploration

Navigate unfamiliar codebases with intelligent context

🛠️ Development Work

Get perfect context when making changes

📝 Documentation

Build comprehensive, living documentation

🔄 Code Reviews

Understand changes in context

🎓 Learning

Understand architecture and patterns

📚 Resources

Available MCP Resources

• pcm://help - Complete help documentation

Related Links

• Model Context Protocol
• Claude Desktop
• MCP Server Registry

🚨 Troubleshooting

Common Issues

MCP Server not found

# Check global installation
npm list -g pcm-mcp-server

# Or use full path in config
which pcm-mcp-server

Permission errors

# Fix executable permissions
chmod +x /path/to/pcm-mcp-server/dist/index.js

Config not loading

• Ensure pcm.config.json exists in pcm-tool/ directory
• Check JSON syntax with cat pcm-tool/pcm.config.json | jq

Debug Mode

{
  "mcpServers": {
    "pcm": {
      "command": "pcm-mcp-server",
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

📄 License

MIT License - see file for details.

🤝 Contributing

See for development setup and contribution guidelines.

📦 Publishing

This package is published to npm and listed in the MCP registry for easy discovery.

Transform your codebase into an intelligent context system. Perfect for LLM-assisted development. ✨