contextmanager

# 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](./developer/README.md) - [Project Server](./project/README.md) - [Student Server](./student/README.md) - [Qualitative Research Server](./qualitativeresearch/README.md) - [Quantitative Research Server](./quantitativeresearch/README.md) ## 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: ```bash npx github:tejpalvirk/contextmanager ``` ### Global Installation Install globally to make all servers available as commands: ```bash npm install -g github:tejpalvirk/contextmanager ``` Then run: ```bash mcp-server-contextmanager ``` Or run a specific domain server directly: ```bash contextmanager-developer contextmanager-project contextmanager-student contextmanager-qualitativeresearch contextmanager-quantitativeresearch ``` ### Clone and Build from Source For development or customization: ```bash git clone https://github.com/tejpalvirk/contextmanager.git cd contextmanager npm install npm run build ``` Then run: ```bash node main/index.js ``` ## Command-Line Arguments The Context Manager and domain servers accept the following command-line arguments: ```bash # 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: ```bash # 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 ```javascript // 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 ```javascript // 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: ```json { "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](https://semver.org/): - **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 ```bash npm install npm run build ``` ### Testing ```bash npm test ``` ## License MIT ## Acknowledgments This project builds on the Model Context Protocol created by Anthropic for Claude.