Carbon MCP

# Carbon MCP - Complete Project Index Quick reference to all files and their purposes. ## 📁 Root Files | File | Purpose | |------|---------| | `package.json` | Project dependencies and scripts | | `tsconfig.json` | TypeScript configuration | | `jest.config.js` | Jest test configuration | | `.eslintrc.js` | ESLint rules and configuration | | `.gitignore` | Git ignore patterns | | `LICENSE` | MIT License | | `README.md` | Main project documentation | | `QUICKSTART.md` | Quick start guide | | `CONTRIBUTING.md` | Contribution guidelines | | `PROJECT_SUMMARY.md` | Project overview and status | | `PROJECT_INDEX.md` | This file - complete file index | ## 🔧 Source Code (`src/`) ### Server (`src/server/`) | File | Purpose | |------|---------| | `index.ts` | Express server bootstrap | | `toolRegistry.ts` | Tool registration and schema mapping | ### Tools (`src/server/tools/`) | File | Purpose | Status | |------|---------|--------| | `generateComponent.ts` | Generate Carbon React components | ✅ Complete | | `generateComponent.test.ts` | Tests for generateComponent | ✅ Complete | | `codemodReplace.ts` | Apply codemods to transform code | ✅ Complete | | `codemodReplace.test.ts` | Tests for codemodReplace | ✅ Complete | | `searchDocs.ts` | Search Carbon documentation | ✅ Complete | | `tokenConverter.ts` | Convert design tokens | ✅ Complete | | `validateComponent.ts` | Validate Carbon component usage | ✅ Complete | | `themePreview.ts` | Generate theme preview HTML | ✅ Complete | | `figmaSync.ts` | Figma integration (scaffold) | ✅ Complete | ### Utilities (`src/lib/`) | File | Purpose | |------|---------| | `logger.ts` | Structured logging with redaction | | `logger.test.ts` | Tests for logger | | `fileUtils.ts` | Safe file operations | | `templateUtils.ts` | Template rendering with Mustache | | `codemodUtils.ts` | Code transformation with jscodeshift | | `diffUtils.ts` | Unified diff generation and application | | `tokenUtils.ts` | Design token conversion utilities | ### Schemas (`src/schemas/`) | File | Purpose | |------|---------| | `generateComponent.json` | Schema for generateComponent tool | | `codemodReplace.json` | Schema for codemodReplace tool | | `searchDocs.json` | Schema for searchDocs tool | | `tokenConverter.json` | Schema for tokenConverter tool | | `validateComponent.json` | Schema for validateComponent tool | ### Templates (`src/templates/`) | File | Purpose | |------|---------| | `component.tsx.tpl` | Component template (Mustache) | | `story.stories.tsx.tpl` | Storybook story template | | `test.tpl` | Jest test template | ### Documentation Index (`src/docsIndex/`) Generated by `npm run index-docs`. Contains indexed Carbon documentation for search. ## 📝 Documentation (`mcp-prompt/`) | File | Purpose | |------|---------| | `carbon-mcp-prompt.txt` | MCP system prompt and instructions | | `examples.md` | Detailed usage examples for all tools | ## 🎨 Demo Application (`demo/demo-app/`) | File | Purpose | |------|---------| | `package.json` | Demo app dependencies | | `index.html` | HTML entry point | | `vite.config.ts` | Vite configuration | | `README.md` | Demo app documentation | | `src/main.tsx` | React app entry point | | `src/App.tsx` | Main app component | ## 🔄 CI/CD (`.github/workflows/`) | File | Purpose | |------|---------| | `ci.yml` | GitHub Actions CI/CD pipeline | ## 🛠️ Scripts (`scripts/`) | File | Purpose | |------|---------| | `index-docs.ts` | Index Carbon documentation for search | ## 📊 File Statistics ### By Type - **TypeScript files**: 20+ - **Test files**: 3+ - **JSON schemas**: 5 - **Templates**: 3 - **Markdown docs**: 10+ - **Configuration files**: 5 ### By Category - **Server code**: 8 files - **Utilities**: 7 files - **Tests**: 3 files - **Schemas**: 5 files - **Documentation**: 10 files - **Configuration**: 5 files - **Demo app**: 6 files ## 🎯 Key Entry Points ### For Users 1. **Start here**: `README.md` 2. **Quick start**: `QUICKSTART.md` 3. **Examples**: `mcp-prompt/examples.md` 4. **Server entry**: `src/server/index.ts` ### For Developers 1. **Contributing**: `CONTRIBUTING.md` 2. **Architecture**: `PROJECT_SUMMARY.md` 3. **Tool registry**: `src/server/toolRegistry.ts` 4. **Utilities**: `src/lib/` ### For Tools 1. **Tool handlers**: `src/server/tools/` 2. **Schemas**: `src/schemas/` 3. **Templates**: `src/templates/` 4. **Tests**: `*.test.ts` files ## 🔍 Finding Specific Features ### Want to add a new tool? 1. Create handler in `src/server/tools/yourTool.ts` 2. Create schema in `src/schemas/yourTool.json` 3. Register in `src/server/toolRegistry.ts` 4. Add tests in `src/server/tools/yourTool.test.ts` 5. Update `README.md` and `examples.md` ### Want to modify logging? - Edit `src/lib/logger.ts` - Tests in `src/lib/logger.test.ts` ### Want to change templates? - Edit files in `src/templates/` - Template rendering logic in `src/lib/templateUtils.ts` ### Want to add codemods? - Add to `src/lib/codemodUtils.ts` - Test in `src/server/tools/codemodReplace.test.ts` ## 📦 Generated Directories These directories are created when the project runs: - `dist/` - TypeScript compilation output (gitignored) - `node_modules/` - Dependencies (gitignored) - `coverage/` - Test coverage reports (gitignored) - `src/docsIndex/` - Indexed documentation (generated) - `theme-previews/` - Generated theme previews (user-created) - `src/components/` - Generated components (user-created) ## 🚀 Quick Commands ```bash # Development npm run dev # Start dev server npm test # Run tests npm run lint # Lint code npm run build # Build project # Documentation npm run index-docs # Index Carbon docs # Demo cd demo/demo-app npm install npm run dev # Start demo app ``` ## 📚 Documentation Order Recommended reading order: 1. `README.md` - Overview and features 2. `QUICKSTART.md` - Get started quickly 3. `mcp-prompt/examples.md` - See examples 4. `PROJECT_SUMMARY.md` - Understand architecture 5. `CONTRIBUTING.md` - Learn to contribute 6. `src/server/tools/` - Study tool implementations ## 🎓 Learning Path ### Beginner 1. Read `README.md` 2. Follow `QUICKSTART.md` 3. Try examples from `mcp-prompt/examples.md` 4. Run the demo app ### Intermediate 1. Explore `src/server/tools/` 2. Read `src/lib/` utilities 3. Study schemas in `src/schemas/` 4. Run and modify tests ### Advanced 1. Read `CONTRIBUTING.md` 2. Study `src/server/index.ts` and `toolRegistry.ts` 3. Implement a new tool 4. Contribute improvements ## 🔗 Cross-References - Tool implementations reference schemas in `src/schemas/` - Tools use utilities from `src/lib/` - Tests mock utilities where needed - Documentation references all tools - Templates are used by `generateComponent` tool ## ✅ Project Checklist - [x] All core tools implemented - [x] Comprehensive test suite - [x] Complete documentation - [x] Demo application - [x] CI/CD pipeline - [x] Security measures - [x] Error handling - [x] Logging infrastructure - [x] Type safety (TypeScript) - [x] Code quality (ESLint) --- **Total Files**: 50+ **Lines of Code**: 5,000+ **Lines of Documentation**: 2,000+ **Last Updated**: November 2, 2025 For questions about specific files, see the relevant documentation or the file's inline comments.