project-customization-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,373 @@
+# Project Customization MCP
+
+An MCP (Model Context Protocol) server that automates project customization by analyzing your codebase and generating configuration files based on industry best practices.
+
+**Platform-agnostic**: Works with any IDE, editor, or AI tool that supports the Model Context Protocol (VS Code, JetBrains, Cursor, Claude, etc.)
+
+## Features
+
+### 🔍 Intelligent Project Analysis
+
+- **Auto-detect project type**: Node.js, Python, .NET, and more
+- **Framework recognition**: React, Vue, Next.js, Angular, FastAPI, Django, etc.
+- **Language detection**: TypeScript, JavaScript, Python, C#, Go, Ruby, Java, etc.
+- **Structure scanning**: Analyzes file organization and project layout
+- **Gap detection**: Identifies missing customization files
+
+### 📝 Automated File Generation
+
+- **Customization instructions** - Creates project-specific guidelines
+- **README updates** - Generates comprehensive documentation
+- **Best practices** - Applies industry standards to your project
+- **Recommendations** - Suggests improvements for your codebase
+
+### 🎯 Tools
+
+- `analyze_project` - Scan project and detect frameworks/languages
+- `generate_copilot_instructions` - Create customization files
+- `update_readme` - Generate or enhance README
+- `get_customization_recommendations` - Get actionable suggestions
+
+### 📚 Resources
+
+- **Project Metadata** - Project type, frameworks, languages
+- **Project Structure** - Directory organization and file tree
+- **Current Guidelines** - Existing customization files
+- **README** - Current documentation
+
+### 💬 Prompt Templates
+
+- **analyze-and-customize** - Full workflow (analyze → generate → update)
+- **generate-instructions-only** - Create just the instruction file
+- **review-and-improve** - Review existing customizations
+
+## Installation
+
+### Option 1: Using npx (Recommended - No Installation Needed)
+
+```json
+{
+  "mcpServers": {
+    "project-customization": {
+      "command": "npx",
+      "args": ["-y", "project-customization-mcp"]
+    }
+  }
+}
+```
+
+### Option 2: Global npm Installation
+
+```powershell
+npm install -g project-customization-mcp
+```
+
+Then configure:
+
+```json
+{
+  "mcpServers": {
+    "project-customization": {
+      "command": "project-customization-mcp"
+    }
+  }
+}
+```
+
+### Option 3: Local Installation
+
+```powershell
+npm install project-customization-mcp
+```
+
+Configure with relative path:
+
+```json
+{
+  "mcpServers": {
+    "project-customization": {
+      "command": "node",
+      "args": ["./node_modules/project-customization-mcp/build/index.js"]
+    }
+  }
+}
+```
+
+## Configuration
+
+### VS Code / Cursor / Other IDE
+
+1. Open MCP configuration (varies by IDE):
+   - VS Code: `Ctrl+Shift+P` → "MCP: Open User Configuration"
+   - Or edit manually in settings
+
+2. Add server config (use Option 1, 2, or 3 above)
+
+3. Restart IDE or reload window
+
+### Claude / Other Clients
+
+Refer to your client's MCP configuration documentation and add the server using one of the installation options above.
+
+## Usage
+
+### Quick Start: Free-form Chat
+
+Open your IDE's chat and type:
+
+```
+Analyze my project and set up customization based on best practices
+```
+
+The server will:
+
+1. ✅ Analyze your project structure
+2. ✅ Detect frameworks and languages
+3. ✅ Generate `.github/copilot-instructions.md` (if missing)
+4. ✅ Update README with guidelines
+5. ✅ Provide improvement recommendations
+
+### Using Prompts (Slash Commands)
+
+If your client supports prompt templates:
+
+```
+/project-customization.analyze-and-customize
+/project-customization.generate-instructions-only
+/project-customization.review-and-improve
+```
+
+### Add Resources to Context
+
+Add project context to your chat:
+
+- "Add Context" or similar option
+- Select "MCP Resources"
+- Choose: Project Metadata, Project Structure, Guidelines, README
+
+### Manual Tool Invocation
+
+Ask your AI to use specific tools:
+
+- "Use the analyze_project tool on my project"
+- "Generate customization instructions for my React app"
+- "Update my README with coding guidelines"
+
+## How It Works
+
+```
+Your Code
+    ↓
+analyze_project (scans structure, detects type/frameworks)
+    ↓
+Project Analysis (type, frameworks, languages, issues)
+    ↓
+generate_copilot_instructions (creates customization file)
+    ↓
+update_readme (adds guidelines and setup instructions)
+    ↓
+get_customization_recommendations (suggests improvements)
+    ↓
+Generated Files + Recommendations
+```
+
+## Example: React TypeScript Project
+
+### Input
+
+```
+"Analyze my React TypeScript project and set up customization"
+```
+
+### Generated Files
+
+**`.github/copilot-instructions.md`:**
+
+```markdown
+# Project Guidelines
+
+## Overview
+
+- **Type**: Node.js
+- **Framework**: React
+- **Language**: TypeScript
+
+## Code Style
+
+- Use functional components with hooks
+- Maintain strict TypeScript (no `any`)
+- ESLint + Prettier for formatting
+- camelCase for variables/functions, PascalCase for components
+
+## Structure
+
+- src/components - React components
+- src/pages - Page components
+- src/utils - Utilities
+- src/hooks - Custom hooks
+- src/types - TypeScript types
+
+[... more guidelines ...]
+```
+
+**`README.md`** (updated with):
+
+- Project description
+- Prerequisites and setup
+- Installation commands
+- Development guidelines
+- Best practices for the framework
+
+### Recommendations Provided
+
+- "Enable strict TypeScript mode"
+- "Add unit testing framework"
+- "Configure git hooks for commits"
+- "Set up CI/CD pipeline"
+
+## Customization
+
+The server comes with sensible defaults for common frameworks. To customize for your team:
+
+1. Fork/clone the repository
+2. Edit `src/utils/bestPractices.ts`:
+   - Modify `generateCopilotInstructions()` for your standards
+   - Adjust `generateReadmeContent()` for your format
+   - Customize `generateRecommendations()` for your priorities
+
+3. Build: `npm run build`
+4. Publish: `npm publish` (or use locally with path)
+
+## Supported Project Types
+
+| Type          | Status             |
+| ------------- | ------------------ |
+| Node.js / npm | ✅ Full Support    |
+| TypeScript    | ✅ Full Support    |
+| React         | ✅ Full Support    |
+| Vue.js        | ✅ Full Support    |
+| Next.js       | ✅ Full Support    |
+| Python        | ✅ Full Support    |
+| .NET          | ✅ Full Support    |
+| Other         | ✅ Generic Support |
+
+## Architecture
+
+```
+src/
+├── index.ts                 # Server startup
+├── server.ts                # MCP setup & registration
+├── tools.ts                 # Tool implementations
+├── resources.ts             # Resource providers
+├── prompts.ts               # Prompt templates
+├── types.ts                 # TypeScript types
+└── utils/
+    ├── fileHandler.ts       # File I/O
+    ├── projectScanner.ts    # Project analysis
+    ├── bestPractices.ts     # Customization templates
+    ├── validator.ts         # Input validation
+    └── logger.ts            # Logging
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 16+
+- npm or yarn
+
+### Setup
+
+```powershell
+git clone https://github.com/yourusername/project-customization-mcp.git
+cd project-customization-mcp
+npm install
+npm run build
+```
+
+### Development Mode
+
+```powershell
+npm run dev
+```
+
+### Build for Production
+
+```powershell
+npm run build
+```
+
+## Contributing
+
+Contributions welcome! Areas for enhancement:
+
+- [ ] Support for more languages/frameworks
+- [ ] Custom organization templates
+- [ ] Integration with CI/CD systems
+- [ ] Linting and formatting configuration generation
+- [ ] Test setup automation
+- [ ] Documentation generators
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Troubleshooting
+
+### Server not connecting
+
+1. Check MCP configuration syntax
+2. Verify command path is correct
+3. Ensure `build/index.js` exists (run `npm run build`)
+4. Check IDE logs for errors
+
+### Tools not appearing
+
+1. Reload IDE window
+2. Restart IDE completely
+3. Verify MCP server is running (check IDE status)
+4. Check server logs for errors
+
+### File permissions
+
+- Ensure write access to project directory
+- Check that `.github/` directory can be created
+
+## FAQ
+
+**Q: Will this modify my existing files?**  
+A: By default, it creates new files or updates README by appending. Existing instructions are backed up.
+
+**Q: What if my project is not detected correctly?**  
+A: Check for standard configuration files (package.json, pyproject.toml, etc.). You can also provide hints through chat context.
+
+**Q: Can I use this for multiple projects?**  
+A: Yes! Configure once and use with any project. It auto-detects project type.
+
+**Q: Is this IDE-specific?**  
+A: No! It's a standard MCP server. Works with any MCP-compatible client.
+
+**Q: Can I customize the guidelines?**  
+A: Yes! Fork the repo and edit `bestPractices.ts` for your organization's standards.
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file
+
+## Support
+
+- 📖 [GitHub Wiki](https://github.com/yourusername/project-customization-mcp/wiki)
+- 🐛 [Report Issues](https://github.com/yourusername/project-customization-mcp/issues)
+- 💬 [Discussions](https://github.com/yourusername/project-customization-mcp/discussions)
+
+## Roadmap
+
+- [ ] Web-based configuration UI
+- [ ] Organization-specific templates library
+- [ ] Linter/formatter configuration generation
+- [ ] Test framework setup automation
+- [ ] Git hooks generation (Husky, etc.)
+- [ ] Pre-commit configuration
+- [ ] EditorConfig generation
+
+---
+
+**Made for the Model Context Protocol** | Works with any MCP-compatible client

package/build/index.d.ts

@@ -0,0 +1 @@
+export {};

package/build/index.js

@@ -0,0 +1,29 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { setupMcpServer } from './server.js';
+import { logger } from './utils/logger.js';
+/**
+ * Main entry point for the MCP server
+ * Sets up stdio transport and starts the server
+ */
+async function main() {
+    try {
+        logger.info('Starting VS Code Customization MCP Server...');
+        // Initialize server with tools, resources, and prompts
+        const server = setupMcpServer();
+        // Set up stdio transport for local communication with VS Code
+        const transport = new StdioServerTransport();
+        // Connect server to transport
+        await server.connect(transport);
+        logger.info('MCP Server is running and ready to accept connections');
+    }
+    catch (error) {
+        logger.error('Fatal error starting MCP server', error);
+        process.exit(1);
+    }
+}
+// Start the server
+main().catch((error) => {
+    console.error('Unhandled error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;;GAGG;AACH,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;QAE5D,uDAAuD;QACvD,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;QAEhC,8DAA8D;QAC9D,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAE7C,8BAA8B;QAC9B,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEhC,MAAM,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,CAAC,CAAC;QACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,mBAAmB;AACnB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;IACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/build/prompts.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prompt templates for MCP server
+ * Pre-built prompts to guide the customization workflow
+ */
+export interface PromptTemplate {
+    name: string;
+    description: string;
+    arguments?: PromptArgument[];
+}
+export interface PromptArgument {
+    name: string;
+    description: string;
+    required?: boolean;
+}
+/**
+ * Available prompt templates
+ */
+export declare const PROMPT_TEMPLATES: PromptTemplate[];
+/**
+ * Get prompt content by name
+ */
+export declare function getPromptContent(promptName: string): string;
+/**
+ * Get all prompt templates
+ */
+export declare function getAllPrompts(): PromptTemplate[];
+/**
+ * Validate prompt name
+ */
+export declare function isValidPromptName(name: string): boolean;

package/build/prompts.js

@@ -0,0 +1,98 @@
+/**
+ * Prompt templates for MCP server
+ * Pre-built prompts to guide the customization workflow
+ */
+/**
+ * Available prompt templates
+ */
+export const PROMPT_TEMPLATES = [
+    {
+        name: 'analyze-and-customize',
+        description: 'Comprehensive prompt to analyze a VS Code project and set up customization files (instructions, README, guidelines)',
+        arguments: [
+            {
+                name: 'projectPath',
+                description: 'Path to the project to analyze and customize',
+                required: false,
+            },
+        ],
+    },
+    {
+        name: 'generate-instructions-only',
+        description: 'Generate only the Copilot custom instructions file based on project analysis',
+        arguments: [
+            {
+                name: 'projectPath',
+                description: 'Path to the project',
+                required: false,
+            },
+        ],
+    },
+    {
+        name: 'review-and-improve',
+        description: 'Review existing project customizations and suggest improvements',
+        arguments: [
+            {
+                name: 'projectPath',
+                description: 'Path to the project',
+                required: false,
+            },
+        ],
+    },
+];
+/**
+ * Get prompt content by name
+ */
+export function getPromptContent(promptName) {
+    switch (promptName) {
+        case 'analyze-and-customize':
+            return `You are a VS Code customization expert. Your task is to analyze the provided project and help customize it for optimal Copilot experience.
+
+Use the following tools in sequence:
+1. First, analyze the project using the \`analyze_project\` tool to understand its structure, type, and current customization status
+2. Review the analysis results to identify gaps and opportunities
+3. Generate Copilot custom instructions using the \`generate_copilot_instructions\` tool
+4. Update or create a README with guidelines using the \`update_readme\` tool
+5. Explain what was done and provide recommendations for further improvements
+
+The goal is to establish a solid foundation of project customization that will improve developer experience when using Copilot.`;
+        case 'generate-instructions-only':
+            return `You are a VS Code customization expert focused on Copilot instructions.
+
+Your task:
+1. Analyze the project using the \`analyze_project\` tool
+2. Generate appropriate Copilot custom instructions using the \`generate_copilot_instructions\` tool
+3. Provide a summary of what instructions were created and why they're important for this project
+
+Focus on creating clear, actionable guidelines that reflect the project's technology stack and best practices.`;
+        case 'review-and-improve':
+            return `You are a code quality and customization expert.
+
+Your task:
+1. Analyze the project using the \`analyze_project\` tool
+2. Get customization recommendations using the \`get_customization_recommendations\` tool
+3. Review existing customization files (README, instructions) by reading the project resources
+4. Provide detailed recommendations for:
+   - What customization improvements are needed
+   - How to enhance existing guidelines
+   - Best practices that aren't yet documented
+   - Potential issues or gaps in the current setup
+
+Be constructive and provide actionable advice.`;
+        default:
+            return `Unknown prompt: ${promptName}`;
+    }
+}
+/**
+ * Get all prompt templates
+ */
+export function getAllPrompts() {
+    return PROMPT_TEMPLATES;
+}
+/**
+ * Validate prompt name
+ */
+export function isValidPromptName(name) {
+    return PROMPT_TEMPLATES.some((p) => p.name === name);
+}
+//# sourceMappingURL=prompts.js.map

package/build/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAqB;IAChD;QACE,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EACT,qHAAqH;QACvH,SAAS,EAAE;YACT;gBACE,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,8CAA8C;gBAC3D,QAAQ,EAAE,KAAK;aAChB;SACF;KACF;IACD;QACE,IAAI,EAAE,4BAA4B;QAClC,WAAW,EAAE,8EAA8E;QAC3F,SAAS,EAAE;YACT;gBACE,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,qBAAqB;gBAClC,QAAQ,EAAE,KAAK;aAChB;SACF;KACF;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,iEAAiE;QAC9E,SAAS,EAAE;YACT;gBACE,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,qBAAqB;gBAClC,QAAQ,EAAE,KAAK;aAChB;SACF;KACF;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,uBAAuB;YAC1B,OAAO;;;;;;;;;gIASmH,CAAC;QAE7H,KAAK,4BAA4B;YAC/B,OAAO;;;;;;;+GAOkG,CAAC;QAE5G,KAAK,oBAAoB;YACvB,OAAO;;;;;;;;;;;;+CAYkC,CAAC;QAE5C;YACE,OAAO,mBAAmB,UAAU,EAAE,CAAC;IAC3C,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/build/resources.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Resource providers for MCP server
+ * Exposes project data as resources that Copilot can access
+ */
+export interface Resource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+export declare class ResourceProviders {
+    /**
+     * Get project metadata resource
+     */
+    static getProjectMetadataResource(projectPath?: string): Promise<Resource & {
+        content: string;
+    }>;
+    /**
+     * Get project structure resource
+     */
+    static getProjectStructureResource(projectPath?: string): Promise<Resource & {
+        content: string;
+    }>;
+    /**
+     * Get current customization guidelines resource
+     */
+    static getGuidelinesResource(projectPath?: string): Promise<Resource & {
+        content: string;
+    }>;
+    /**
+     * Get README resource
+     */
+    static getReadmeResource(projectPath?: string): Promise<Resource & {
+        content: string;
+    }>;
+    /**
+     * List all available resources
+     */
+    static listResources(): Promise<Resource[]>;
+    /**
+     * Get resource by URI
+     */
+    static getResource(uri: string, projectPath?: string): Promise<{
+        content: string;
+        mimeType: string;
+    }>;
+}