MCP Context Manager

MCP Context Manager

A collection of Model Context Protocol (MCP) servers to enhance AI models with persistent context across work sessions throughout the project lifecycle.

Context for each project is stored in a domain-specific knowledge graph handled by the domain's server. All domain servers can be managed through a central Context Manager that provides unified access.

Each domain server is also a standalone MCP Server that you can use on its own without the Context Manager.

Features

• Persistent Context: Easily buildcontext, loadcontext, and deletecontext as you progress from idea to production/publication/completion
• Efficienct Access: Let AI models grab the exact context they need when they need it
• Session Management:
  1. startsession tool to get an overview of what you've been working on in past sessions
  2. endsession tool to analyze the entire session and update knowledge graph for future sessions
• Cross-Domain Support: Work with multiple knowledge domains through a single interface, including creating relationships between entities in different domains

Why knowledge graphs?

To free up the context window (performance), and minimize token cost (efficiency).

Available Servers

The contextmanager orchestrates several domain-specific MCP servers:

1. Developer MCP Server: software development context with entities like projects, components, and tasks. Includes status tracking (inactive, active, complete), priority management (high, low), and task sequencing through precedes relations.

2. Project MCP Server: project management context with entities like projects, tasks, and resources. Features status management (inactive, active, complete), priority assignment (high, low), and task sequencing capabilities.

3. Student MCP Server: educational context with entities like courses, assignments, and exams. Supports tracking status (active, completed, pending, abandoned), prioritizing assignments (high, low), and creating learning sequences.

4. Qualitative Research MCP Server: qualitative research context with entities like studies, participants, and interviews. Includes research activity status tracking (active, completed, pending, abandoned), priority management (high, low), and analysis sequencing.

5. Quantitative Research MCP Server: quantitative research context with entities like datasets, variables, and analyses. Features status management (active, completed, pending, abandoned), priority assignment (high, low), and sequential process management.

For detailed documentation on each domain server, see the README files in their respective directories:

• Developer Server
• Project Server
• Student Server
• Qualitative Research Server
• Quantitative Research Server

Context Manager Benefits

The Context Manager provides:

• Unified Interface: Access all domain servers through a single interface.
• Smart Routing: Automatically routes requests to the appropriate domain server.
• Cross-Domain Context: Maintains references across different domains.
• Consistent Status Management: Standardized approach to status tracking across domains.
• Unified Priority System: Consistent priority management across different contexts.
• Integrated Sequencing: Harmonized approach to sequential workflows across domains.

Implementation

The Context Manager uses the MCP Client SDK to communicate with domain-specific MCP servers. It:

1. Maintains a registry of domain servers with their connection information
2. Creates MCP clients to connect to each domain server
3. Routes requests to the appropriate domain server based on the active domain
4. Provides cross-domain functionality for relating entities across domains
5. Ensures consistent handling of status, priority, and sequential relations

Path Resolution

The Context Manager uses absolute paths constructed at runtime to locate domain servers. If you need to modify paths to domain servers, update the domains array in main/index.ts.

Installation & Usage

You can use the MCP Context Manager in several ways:

Using npx (Recommended)

Run directly with npx:

npx github:tejpalvirk/contextmanager

Global Installation

Install globally to make all servers available as commands:

npm install -g github:tejpalvirk/contextmanager

Then run:

mcp-server-contextmanager

Or run a specific domain server directly:

contextmanager-developer
contextmanager-project
contextmanager-student
contextmanager-qualitativeresearch
contextmanager-quantitativeresearch

Clone and Build from Source

For development or customization:

git clone https://github.com/tejpalvirk/contextmanager.git
cd contextmanager
npm install
npm run build

Then run:

node main/index.js

Command-Line Arguments

The Context Manager and domain servers accept the following command-line arguments:

# Run on a specific port (default: 3000)
npx github:tejpalvirk/contextmanager --port 3001

# Enable debug logging
npx github:tejpalvirk/contextmanager --debug

# Specify a config file
npx github:tejpalvirk/contextmanager --config ./my-config.json

# Run only specific domain servers
npx github:tejpalvirk/contextmanager --domains developer,project

Environment Variables

Each domain server supports the following environment variables to customize where data is stored:

• MEMORY_FILE_PATH: Path where the knowledge graph data will be stored

  • Can be absolute or relative (relative paths use current working directory)
  • Default: <domain_directory>/memory.json

• SESSIONS_FILE_PATH: Path where session data will be stored

  • Can be absolute or relative (relative paths use current working directory)
  • Default: <domain_directory>/sessions.json

Example usage:

# Store data in the current directory
MEMORY_FILE_PATH="./my-dev-memory.json" SESSIONS_FILE_PATH="./my-dev-sessions.json" npx github:tejpalvirk/contextmanager

# Store data in a specific location (absolute path)
MEMORY_FILE_PATH="/path/to/data/developer-memory.json" npx github:tejpalvirk/contextmanager

# Store data in user's home directory
MEMORY_FILE_PATH="$HOME/contextmanager/memory.json" npx github:tejpalvirk/contextmanager

Interacting with Domain Servers

Domain Management

Use the setActiveDomain tool to select which domain you want to work with:

setActiveDomain(domain="developer")

Session Management

Start a new session for the active domain:

startsession(domain="developer")

End a session when you're done:

endsession(sessionId="session_id_here", stage="assembly", stageNumber=6, totalStages=6, nextStageNeeded=false)

Context Operations

Build context for the active domain:

buildcontext(type="entities", data={...})

Load context for a specific entity:

loadcontext(entityName="MyProject", entityType="project")

Delete context:

deletecontext(type="entities", data={...})

Entity Status and Priority Management

Assign status to entities:

buildcontext(type="relations", data=[
  { from: "LoginFeature", to: "active", relationType: "has_status" }
])

Set entity priorities:

buildcontext(type="relations", data=[
  { from: "BugFix", to: "high", relationType: "has_priority" }
])

Define sequential relationships:

buildcontext(type="relations", data=[
  { from: "DataModel", to: "UserInterface", relationType: "precedes" }
])

Example: Working with the Developer Domain

// Set the active domain to developer
setActiveDomain(domain="developer")

// Start a new session
startsession(domain="developer")

// Create a new project entity
buildcontext(type="entities", data={
  "entityType": "project",
  "name": "MyProject",
  "description": "A sample project",
  "language": "TypeScript",
  "framework": "React"
})

// Load context for the project
loadcontext(entityName="MyProject", entityType="project")

// Create a component for the project and set its status to active
buildcontext(type="entities", data={
  "entityType": "component",
  "name": "AuthService",
  "project": "MyProject",
  "description": "Authentication service component",
  "dependencies": ["UserService"]
})

buildcontext(type="relations", data=[
  { from: "AuthService", to: "active", relationType: "has_status" },
  { from: "AuthService", to: "high", relationType: "has_priority" }
])

Cross-Domain Operations

Create relationships between entities in different domains:

relateCrossDomain(fromDomain="developer", fromEntity="ProjectX", toDomain="project", toEntity="ProjectX", relationType="manages")

Example: Cross-Domain Integration

// Create relationship between developer project and project management task
relateCrossDomain(
  fromDomain="developer", 
  fromEntity="MyProject", 
  toDomain="project", 
  toEntity="ProjectX", 
  relationType="manages"
)

Integration with Claude

In Claude Desktop, configure the Context Manager in settings:

{
  "mcpServers": {
    "contextmanager": {
      "command": "npx",
      "args": [
        "-y",
        "github:tejpalvirk/contextmanager"
      ],
      "options": {
        "port": 3000,
        "domains": ["developer", "project", "student"]
      }
    }
  }
}

Troubleshooting

Common Issues

1. Port Already in Use:

   Error: listen EADDRINUSE: address already in use :::3000
   

   Solution: Use the --port option to specify a different port.

2. Connection Refused:

   Error: connect ECONNREFUSED 127.0.0.1:3000
   

   Solution: Ensure the server is running and accessible at the specified address.

3. Domain Server Not Found:

   Error: Domain server 'developer' not found
   

   Solution: Check that the domain name is correct and the server is registered in the Context Manager.

4. Path Resolution Errors:

   Error: Cannot find module '...'
   

   Solution: Ensure all paths in the domains array in main/index.ts are correctly specified.

5. Method Not Found:

   Error: Method 'buildcontext' not found in domain 'developer'
   

   Solution: Verify the method name and ensure it is supported by the domain server.

6. Invalid Status or Priority Value:

   Error: Invalid status value 'in_progress'. Valid values are: inactive, active, complete
   

   Solution: Ensure you're using the correct status values for the specific domain.

Next Steps

• Replace JSON for YAML for 20-30% improvement in token efficiency
• Explore Knowledge Graphs in Markdown

Versioning

This package follows Semantic Versioning:

• MAJOR: Incompatible API changes
• MINOR: Backwards-compatible functionality additions
• PATCH: Backwards-compatible bug fixes

Current version: 1.0.0

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Coding Standards

• Use TypeScript for all new code
• Follow the existing code style
• Add tests for new functionality
• Update documentation as needed

Development

Prerequisites

• Node.js v16 or higher
• npm v7 or higher

Building

npm install
npm run build

Testing

npm test

License

MIT

Acknowledgments

This project builds on the Model Context Protocol created by Anthropic for Claude.