{"_id":"@apposite/context-mcp","name":"@apposite/context-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@apposite/context-mcp","version":"1.0.0","description":"Context-aware guidance MCP server for AI assistants","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"bin":{"context-mcp":"dist/index.js"},"engines":{"node":">=18.0.0"},"keywords":["mcp","model-context-protocol","context","guidance","ai","ai-assistant","claude","workflow"],"repository":{"type":"git","url":"git+https://github.com/YOURUSER/context-mcp.git"},"homepage":"https://github.com/YOURUSER/context-mcp#readme","bugs":{"url":"https://github.com/YOURUSER/context-mcp/issues"},"scripts":{"build":"tsc","watch":"tsc --watch","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","start":"node dist/index.js","prepublishOnly":"npm run lint && npm test && npm run build"},"author":{"name":"YOURNAME","email":"your@email.com"},"license":"ISC","dependencies":{"@modelcontextprotocol/sdk":"^1.24.3","gray-matter":"^4.0.3"},"devDependencies":{"@eslint/js":"^9.39.2","@types/jest":"^30.0.0","@types/node":"^24.10.2","@typescript-eslint/eslint-plugin":"^8.49.0","@typescript-eslint/parser":"^8.49.0","eslint":"^9.39.1","globals":"^16.5.0","jest":"^30.2.0","prettier":"^3.7.4","ts-jest":"^29.4.6","ts-node":"^10.9.2","typescript":"^5.9.3"},"_id":"@apposite/context-mcp@1.0.0","gitHead":"1e2876dcc9e323e50f2238c1f1f14eaadc265625","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-un9mPa9CnuZwGNjnT1rfKbSAHi5TjxkWisDmfvBeJY0dPY2unMSVpd2JeKcHvrP0VmkBEIPHlr3SsVTeezwW3g==","shasum":"e915c6632d11e7ad4aa2ce99e7f34df943d6df9d","tarball":"https://registry.npmjs.org/@apposite/context-mcp/-/context-mcp-1.0.0.tgz","fileCount":51,"unpackedSize":156995,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDdmhL7Kq1yomtfr1yB4IhPsTQd5G9jAsN1eMAsCvEWYQIhAP9Go89w+qULyk9XtuUtiWQmIBJgksvExzyFsF9IVaUY"}]},"_npmUser":{"name":"apposite","email":"jem@apposite.com.au"},"directories":{},"maintainers":[{"name":"apposite","email":"jem@apposite.com.au"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/context-mcp_1.0.0_1768236193776_0.8610663286825344"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-12T16:43:13.668Z","1.0.0":"2026-01-12T16:43:13.932Z","modified":"2026-01-12T16:43:14.186Z"},"maintainers":[{"name":"apposite","email":"jem@apposite.com.au"}],"description":"Context-aware guidance MCP server for AI assistants","homepage":"https://github.com/YOURUSER/context-mcp#readme","keywords":["mcp","model-context-protocol","context","guidance","ai","ai-assistant","claude","workflow"],"repository":{"type":"git","url":"git+https://github.com/YOURUSER/context-mcp.git"},"author":{"name":"YOURNAME","email":"your@email.com"},"bugs":{"url":"https://github.com/YOURUSER/context-mcp/issues"},"license":"ISC","readme":"# Context MCP Server\n\nContext-aware guidance for AI assistants via Model Context Protocol.\n\n## Overview\n\nProvides just-in-time, context-specific guidance to AI assistants as developers move through their workflow. The server loads context-appropriate information and guidance as you transition between different development activities (design, development, debugging, PR review, deployment, operations).\n\n## Features\n\n- **8 Base Contexts**: Design, development, debugging, PR review, deployment, operations, new conversation, post-compaction\n- **Project-Specific Overlays**: Extend base contexts with project-specific guidance\n- **Learning Loop**: Suggest improvements and vote on guidance items\n- **Transition Tracking**: Monitor and analyze context transition patterns\n- **Just-in-Time Loading**: Guidance appears only when relevant to current context\n- **Composition**: Three-layer guidance (base + project + override flags)\n\n## Quick Start\n\n### 1. Installation\n\n```bash\ncd ~/development/context_mcp\nnpm install\nnpm run build\n```\n\n### 2. Claude Desktop Integration\n\nAdd to your Claude Desktop config:\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"context-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/context_mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### 3. Restart Claude Desktop\n\nThe server will automatically:\n- Create `~/.context_mcp/` directory structure\n- Install 8 base context files\n- Initialize learning data storage\n- Start logging to `~/.context_mcp/logs/context-mcp.log`\n\n## Usage\n\n### In Claude Desktop\n\nAfter restarting Claude Desktop, the server provides:\n\n**Resource**: `context://definitions`\n- Auto-loads at session start\n- Lists all available contexts with entry signals and transitions\n\n**Tools**: 4 tools for context management\n- `declare_context_transition`: Declare you're entering a new context (primary)\n- `get_context_guidance`: Fetch guidance for a specific context (secondary)\n- `suggest_guidance`: Submit a suggestion for guidance improvement\n- `vote_on_guidance`: Vote on an existing suggestion\n\n### Manual Server Start\n\nFor testing or validation:\n\n```bash\nnpm start -- --base-path ~/.context_mcp --log-level info\n```\n\n## Configuration\n\n### CLI Arguments\n\n```bash\nnode dist/index.js --base-path <path> --log-level <level>\n```\n\n- `--base-path`: Data directory (default: `~/.context_mcp/`)\n- `--log-level`: Logging verbosity (`error`, `warn`, `info`, `debug`)\n\n### Environment Variables\n\n- `CONTEXT_MCP_BASE_PATH`: Override base path\n- `CONTEXT_MCP_CWD`: Override current working directory\n- `CONTEXT_MCP_LOG_LEVEL`: Override log level\n\n### Directory Structure\n\n```\n~/.context_mcp/\n├── contexts/              # 8 base context markdown files\n│   ├── design.md\n│   ├── development.md\n│   ├── debugging.md\n│   ├── pr-review.md\n│   ├── deployment.md\n│   ├── operations.md\n│   ├── new-conversation.md\n│   └── post-compaction.md\n├── projects/              # Project-specific context overlays (optional)\n│   └── <project-name>/\n│       └── contexts/\n│           └── development.md  # Example project overlay\n├── learning/              # Learning loop data\n│   ├── suggestions.json\n│   ├── votes.json\n│   └── transitions.json\n└── logs/                  # Server logs\n    └── context-mcp.log\n```\n\n## Available Contexts\n\n1. **design**: Architecture planning, technical design, tradeoff analysis\n2. **development**: Inner loop coding, testing, iteration\n3. **debugging**: Issue investigation, log analysis, root cause analysis\n4. **pr-review**: Code review, CI/CD, feedback integration\n5. **deployment**: Release preparation, rollout, monitoring\n6. **operations**: Production monitoring, incident response, maintenance\n7. **new-conversation**: Starting fresh sessions, context introduction\n8. **post-compaction**: Re-establishing context after history compaction\n\nEach context includes:\n- Entry signals (when to use this context)\n- Common transitions (what contexts typically follow)\n- Essential tools (recommended tools for this work)\n- Common workflows (typical task sequences)\n- Success criteria (what \"done\" looks like)\n- Gotchas (common mistakes to avoid)\n\n## Testing\n\n### Run Tests\n\n```bash\n# All tests\nnpm test\n\n# With coverage report\nnpm run test:coverage\n\n# Watch mode\nnpm run test:watch\n```\n\n### Test Coverage\n\nCurrent coverage (57 tests):\n- **Statements**: 97.00%\n- **Branches**: 87.12%\n- **Functions**: 100.00%\n- **Lines**: 96.96%\n\n### MCP Inspector Validation\n\n```bash\nnpx @modelcontextprotocol/inspector dist/index.js\n```\n\nOpens web UI at http://localhost:6274 for interactive testing.\n\n## Development\n\n```bash\n# Build\nnpm run build\n\n# Watch mode\nnpm run watch\n\n# Lint\nnpm run lint\n\n# Format\nnpm run format\n```\n\n## Project Structure\n\n```\nsrc/\n├── services/       # Core services (ContextLoader, GuidanceManager, etc.)\n├── tools/          # MCP tool implementations\n├── resources/      # MCP resource implementations\n├── types/          # TypeScript type definitions\n└── utils/          # Utility functions\n\ntests/\n├── unit/           # Unit tests\n└── integration/    # Integration tests\n```\n\n## Architecture\n\n### Core Services\n\n1. **ContextLoader**: Markdown file loading, YAML frontmatter parsing, caching\n2. **GuidanceManager**: Three-layer composition (base + project + override flags)\n3. **LearningEngine**: Suggestions and voting with JSON persistence\n4. **TransitionLogger**: Transition tracking with filtering and analysis\n\n### MCP Resources\n\n**context://definitions**\n- Lists all available contexts with metadata\n- Auto-loads at session start\n- Provides entry signals and common transitions\n\n### MCP Tools\n\n**declare_context_transition**\n- Primary tool for context declarations\n- Records transition with timestamp\n- Returns composed guidance (base + project)\n- Optional previous_context for transition tracking\n\n**get_context_guidance**\n- Secondary tool for fetching guidance\n- Takes context name only\n- No transition logging\n- Useful for reference lookups\n\n**suggest_guidance**\n- Submit improvement suggestions\n- Records section and description\n- Returns UUID for tracking\n- Enables continuous improvement\n\n**vote_on_guidance**\n- Vote on existing suggestions\n- Fuzzy matching within sections\n- Up/down voting\n- Tracks voting patterns\n\n## Usage Examples\n\n### Declaring Context Transition\n\n```typescript\n// When starting development work\n{\n  \"context\": \"development\",\n  \"project\": \"context_mcp\",\n  \"previous_context\": \"design\"\n}\n\n// Returns:\n{\n  \"context\": \"development\",\n  \"guidance\": {\n    \"description\": \"Inner loop coding...\",\n    \"entry_signals\": [...],\n    \"common_transitions\": [...],\n    \"essential_tools\": [...],\n    \"workflows\": [...],\n    \"success_criteria\": [...],\n    \"gotchas\": [...]\n  }\n}\n```\n\n### Submitting Suggestion\n\n```typescript\n{\n  \"context\": \"development\",\n  \"section\": \"essential_tools\",\n  \"description\": \"Add TypeScript compiler as essential tool\",\n  \"content\": \"**tsc**: TypeScript compiler for type checking\"\n}\n\n// Returns: { \"suggestion_id\": \"uuid-here\" }\n```\n\n### Voting on Suggestion\n\n```typescript\n{\n  \"context\": \"development\",\n  \"section\": \"essential_tools\",\n  \"description_match\": \"TypeScript compiler\",\n  \"vote\": \"up\"\n}\n\n// Returns: { \"success\": true, \"message\": \"Vote recorded\" }\n```\n\n## Project-Specific Contexts\n\nCreate project-specific overlays in `~/.context_mcp/projects/<project-name>/contexts/`:\n\n```markdown\n---\ncontext: development\ncompose_with_base: true\nlast_updated: 2025-12-09T00:00:00Z\n---\n\n# Project-Specific Development Context\n\n## Project Tools\n- **npm**: Package management\n- **Jest**: Testing framework\n- **TypeScript**: Primary language\n\n## Project Workflows\n1. Write code\n2. Run tests (`npm test`)\n3. Check types (`npm run type-check`)\n4. Commit changes\n```\n\nThe server will automatically compose base + project guidance when project is detected.\n\n## Monitoring\n\n### View Logs\n\n```bash\ntail -f ~/.context_mcp/logs/context-mcp.log\n```\n\n### Learning Data\n\n```bash\n# View suggestions\ncat ~/.context_mcp/learning/suggestions.json\n\n# View votes\ncat ~/.context_mcp/learning/votes.json\n\n# View transitions\ncat ~/.context_mcp/learning/transitions.json\n```\n\n## Troubleshooting\n\n### Server not appearing in Claude Desktop\n\n1. Check config syntax (Linux): `cat ~/.config/Claude/claude_desktop_config.json`\n2. Verify build: `cd ~/development/context_mcp && npm run build`\n3. Check logs: `tail ~/.context_mcp/logs/context-mcp.log`\n4. Restart Claude Desktop completely\n\n### Context files not loading\n\n1. Verify directory exists: `ls ~/.context_mcp/contexts/`\n2. Check file format (YAML frontmatter + markdown)\n3. Verify compose_with_base flag in frontmatter\n4. Check logs for parsing errors\n\n### Tools not working\n\n1. Verify server is running (check Claude Desktop MCP status)\n2. Check tool arguments match schema\n3. Review server logs for errors\n4. Test with MCP Inspector\n\n## Documentation\n\n- [Project Overview](doc/overview.md) - Concept and rationale\n- [Design Document](doc/design.md) - Detailed technical design\n- [Implementation Plan](doc/implementation_plan.md) - Development roadmap\n- [Implementation Complete](doc/progress/progress_20251209_implementation_complete.md) - Status report\n- [Validation & Deployment](doc/progress/progress_20251209_validation_deployment.md) - Deployment guide\n\n## Contributing\n\nThis is currently a single-user project for personal development workflows. Future versions may support multi-user scenarios and collaboration features.\n\n## License\n\nISC\n","readmeFilename":"README.md","_rev":"1-4e171c1856222b46fb1231312b78a490"}