@stackguide/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,453 @@
+# StackGuide MCP Server
+
+A Model Context Protocol (MCP) server that provides dynamic language and framework context for AI coding assistants. Compatible with **Cursor** and **GitHub Copilot**.
+
+## Features
+
+- 🎯 **Dynamic Context Loading**: Load context based on your project type (Python/Django, React/Node, etc.)
+- 📋 **Rules Management**: Select and apply coding standards, best practices, and security guidelines
+- 📚 **Knowledge Base**: Access architecture patterns, common issues solutions, and code snippets
+- 💾 **Configuration Persistence**: Save and load your preferred configurations
+- 🔄 **Compatible**: Works with both Cursor and GitHub Copilot
+- ✨ **Dynamic Rule Management**: Create, edit, and delete rules at runtime using tools
+- 🌐 **Web Documentation**: Fetch and cache documentation from any URL
+- 📝 **Rule Templates**: Quick-start templates for common rule types (coding-standard, best-practice, security, architecture, testing)
+- 🔗 **Cursor Directory Integration**: Browse, search, and import rules from [cursor.directory](https://cursor.directory/rules/) - a community-driven repository of AI coding rules
+
+## Supported Project Types
+
+| Type | Languages | Frameworks |
+|------|-----------|------------|
+| `python-django` | Python | Django, DRF |
+| `python-fastapi` | Python | FastAPI |
+| `python-flask` | Python | Flask |
+| `react-node` | JavaScript, TypeScript | React, Node.js, Express |
+| `react-typescript` | TypeScript | React |
+| `vue-node` | JavaScript, TypeScript | Vue.js, Node.js |
+| `nextjs` | JavaScript, TypeScript | Next.js, React |
+| `express` | JavaScript, TypeScript | Express.js |
+| `nestjs` | TypeScript | NestJS |
+| `laravel` | PHP | Laravel |
+| `rails` | Ruby | Ruby on Rails |
+| `golang` | Go | - |
+| `rust` | Rust | - |
+
+## Installation
+
+### From npm (Recommended)
+
+```bash
+npm install -g @stackguide/mcp-server
+```
+
+### From Source
+
+```bash
+git clone https://github.com/taimiralain/StackGuide-MCP.git
+cd StackGuide-MCP
+npm install
+npm run build
+```
+
+## Configuration
+
+### For Cursor
+
+Add to your Cursor settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "stackguide": {
+      "command": "npx",
+      "args": ["-y", "@stackguide/mcp-server"]
+    }
+  }
+}
+```
+
+Or if installed from source:
+
+```json
+{
+  "mcpServers": {
+    "stackguide": {
+      "command": "node",
+      "args": ["/path/to/StackGuide-MCP/dist/index.js"]
+    }
+  }
+}
+```
+
+### For VS Code with GitHub Copilot
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "mcpServers": {
+    "stackguide": {
+      "command": "npx",
+      "args": ["-y", "@stackguide/mcp-server"]
+    }
+  }
+}
+```
+
+Or add to your user settings (`settings.json`):
+
+```json
+{
+  "github.copilot.chat.mcpServers": {
+    "stackguide": {
+      "command": "npx",
+      "args": ["-y", "@stackguide/mcp-server"]
+    }
+  }
+}
+```
+
+## Usage
+
+### Available Tools
+
+#### Project Type Management
+- `list_project_types` - List all supported project types
+- `select_project_type` - Activate a project type context
+- `get_current_context` - Get the currently active context
+
+#### Rules Management
+- `list_rules` - List available rules for current project
+- `get_rule` - Get full content of a specific rule
+- `select_rules` - Select which rules to include in context
+- `search_rules` - Search rules by keyword
+
+#### Knowledge Base
+- `list_knowledge` - List knowledge base files
+- `get_knowledge` - Get content of a knowledge file
+- `select_knowledge` - Select knowledge to include
+- `search_knowledge` - Search knowledge base
+
+#### Configuration
+- `save_configuration` - Save current context setup
+- `load_configuration` - Load a saved configuration
+- `list_configurations` - List all saved configurations
+- `delete_configuration` - Delete a configuration
+- `export_configuration` - Export config as JSON
+- `import_configuration` - Import config from JSON
+
+#### Dynamic Rule Management (NEW!)
+- `create_rule` - Create a new custom rule from scratch
+- `create_rule_from_template` - Create a rule using a template
+- `list_rule_templates` - List available rule templates
+- `update_rule` - Update an existing user rule
+- `delete_rule` - Delete a user rule
+- `list_user_rules` - List all user-created rules
+- `export_user_rules` - Export all user rules as JSON
+- `import_user_rules` - Import user rules from JSON
+
+#### Web Documentation (NEW!)
+- `fetch_web_docs` - Fetch documentation from any URL
+- `fetch_multiple_docs` - Fetch multiple URLs at once
+- `get_web_doc` - Get a cached web document
+- `search_web_docs` - Search cached documentation
+- `list_web_docs` - List all cached documents
+- `get_suggested_docs` - Get suggested docs for a project type
+- `remove_web_doc` - Remove a cached document
+
+#### Cursor Directory Integration (NEW!)
+- `browse_cursor_directory` - Browse rules by category from cursor.directory
+- `search_cursor_directory` - Search for rules on cursor.directory
+- `get_cursor_directory_rule` - Get a specific rule by slug
+- `list_cursor_directory_categories` - List all available categories
+- `get_popular_cursor_rules` - Get popular/featured rules
+- `import_cursor_directory_rule` - Import a rule into your local collection
+
+#### Context
+- `get_full_context` - Get complete active context
+- `add_custom_rule` - Add a custom rule
+
+### Example Workflow
+
+1. **Select your project type:**
+   ```
+   Use select_project_type with "react-node"
+   ```
+
+2. **View available rules:**
+   ```
+   Use list_rules to see all available rules
+   ```
+
+3. **Select specific rules:**
+   ```
+   Use select_rules with the IDs of rules you want
+   ```
+
+4. **Save your configuration:**
+   ```
+   Use save_configuration with a name like "My React Setup"
+   ```
+
+5. **Get full context for AI:**
+   ```
+   Use get_full_context to get all selected rules and knowledge
+   ```
+
+### Available Resources
+
+- `rules://{project_type}/all` - All rules for a project type
+- `knowledge://{project_type}/all` - All knowledge for a project type
+- `context://active` - Currently active context (includes rules, user rules, knowledge, and web docs)
+- `user-rules://{project_type}/all` - All user-created rules for a project type
+- `web-doc://{doc_id}` - Specific cached web document
+- `templates://rules` - Available rule templates
+
+### Available Prompts
+
+- `setup_project` - Initialize context for a new project
+- `code_review` - Review code with active rules
+- `apply_patterns` - Apply architecture patterns
+
+## Adding Custom Rules
+
+### Via Tool
+Use the `add_custom_rule` tool with:
+- `name`: Rule name
+- `category`: One of `coding-standards`, `best-practices`, `security`, `performance`, `architecture`, `testing`, `documentation`, `naming-conventions`
+- `content`: Rule content in Markdown
+- `description`: Brief description
+
+### Via Files
+Add Markdown files to the `data/rules/{project-type}/{category}/` directory:
+
+```markdown
+# Rule Title
+
+Description of the rule.
+
+## Guidelines
+
+- Guideline 1
+- Guideline 2
+
+## Examples
+
+```python
+# Code example
+```
+```
+
+## Configuration Storage
+
+User configurations are stored in `~/.stackguide/`:
+- `configurations.json` - All saved configurations
+- `rules/{project-type}/*.json` - User-created rules
+- `web-docs/cache.json` - Cached web documentation
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Run in Development
+
+```bash
+npm run dev
+```
+
+### Project Structure
+
+```
+StackGuide-MCP/
+├── src/
+│   ├── index.ts              # Main entry point
+│   ├── config/
+│   │   ├── types.ts          # TypeScript types
+│   │   └── persistence.ts    # Configuration storage
+│   ├── resources/
+│   │   ├── rulesProvider.ts      # Rules management
+│   │   └── knowledgeProvider.ts  # Knowledge base
+│   └── services/
+│       ├── ruleManager.ts        # Dynamic rule CRUD
+│       └── webDocumentation.ts   # Web docs fetcher
+├── data/
+│   ├── rules/                # Rule files by project type
+│   │   ├── python-django/
+│   │   └── react-node/
+│   └── knowledge/            # Knowledge files by project type
+│       ├── python-django/
+│       └── react-node/
+├── docs/
+│   └── ADDING_CUSTOM_RULES.md   # Guide for adding rules
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Dynamic Rule Management
+
+### Creating Rules from Templates
+
+1. **List available templates:**
+   ```
+   Use list_rule_templates
+   ```
+
+2. **Create a rule from template:**
+   ```
+   Use create_rule_from_template with:
+   - templateId: "coding-standard" 
+   - projectType: "react-node"
+   - name: "My Team Standards"
+   ```
+
+3. **Edit the rule:**
+   ```
+   Use update_rule with the rule ID and new content
+   ```
+
+### Creating Rules from Scratch
+
+```
+Use create_rule with:
+- projectType: "python-django"
+- name: "API Versioning"
+- category: "best-practices"
+- content: "# API Versioning\n\nAlways version your APIs..."
+- description: "Guidelines for API versioning"
+```
+
+## Web Documentation
+
+### Fetching Documentation
+
+```
+Use fetch_web_docs with:
+- url: "https://react.dev/reference/react/useState"
+- projectType: "react-node"  
+- title: "useState Hook"
+```
+
+### Getting Suggestions
+
+```
+Use get_suggested_docs with projectType: "react-node"
+```
+
+This returns popular documentation URLs for the framework.
+
+## Cursor Directory Integration
+
+[cursor.directory](https://cursor.directory/rules/) is a community-driven repository of cursor rules for various technologies. StackGuide-MCP integrates with it to let you:
+
+### Browse Rules by Category
+
+```
+Use browse_cursor_directory with category: "typescript"
+```
+
+Available categories include: typescript, python, react, next.js, vue, django, fastapi, nestjs, prisma, tailwindcss, and many more.
+
+### Search for Rules
+
+```
+Use search_cursor_directory with query: "react hooks best practices"
+```
+
+### Get Popular Rules
+
+```
+Use get_popular_cursor_rules
+```
+
+Returns featured rules from popular frameworks.
+
+### Import Rules
+
+```
+Use import_cursor_directory_rule with:
+- slug: "nextjs-react-typescript-cursor-rules"
+- projectType: "react-typescript"
+- category: "best-practices"
+```
+
+This fetches the rule from cursor.directory and saves it to your local rules collection.
+
+## Publishing to npm
+
+### Prerequisites
+
+1. Create an npm account at [npmjs.com](https://www.npmjs.com/)
+2. Login to npm:
+   ```bash
+   npm login
+   ```
+
+### Steps to Publish
+
+1. **Update version** in `package.json`:
+   ```bash
+   npm version patch  # or minor, major
+   ```
+
+2. **Build the project**:
+   ```bash
+   npm run build
+   ```
+
+3. **Test locally** (optional):
+   ```bash
+   npm link
+   stackguide-mcp  # Test the command
+   npm unlink
+   ```
+
+4. **Publish to npm**:
+   ```bash
+   npm publish --access public
+   ```
+
+   Note: The package is scoped (`@stackguide/mcp-server`), so you need `--access public` for the first publish.
+
+5. **Verify publication**:
+   ```bash
+   npm view @stackguide/mcp-server
+   ```
+
+### Updating the Published Package
+
+```bash
+npm version patch  # Bump version
+npm run build
+npm publish
+```
+
+### Publishing Checklist
+
+- [ ] All tests pass
+- [ ] README is up to date
+- [ ] Version is bumped
+- [ ] Build succeeds
+- [ ] `main` and `bin` fields in package.json point to correct files
+- [ ] Keywords and description are accurate
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add your rules/knowledge files or enhance the server
+4. Submit a pull request
+
+### Adding Support for New Frameworks
+
+1. Add project type to `src/config/types.ts`
+2. Create rule files in `data/rules/{new-type}/`
+3. Create knowledge files in `data/knowledge/{new-type}/`
+
+## License
+
+GPL-3.0 - See [LICENSE](LICENSE) for details.

package/data/knowledge/python-django/architecture/architecture-patterns.md

@@ -0,0 +1,201 @@
+# Django Project Architecture
+
+Recommended architecture patterns for scalable Django applications.
+
+## Layered Architecture
+
+```
+┌─────────────────────────────────────┐
+│           Presentation              │
+│  (Views, Templates, Serializers)    │
+├─────────────────────────────────────┤
+│            Application              │
+│      (Services, Use Cases)          │
+├─────────────────────────────────────┤
+│             Domain                  │
+│   (Models, Business Logic)          │
+├─────────────────────────────────────┤
+│          Infrastructure             │
+│  (Database, External APIs, Cache)   │
+└─────────────────────────────────────┘
+```
+
+## Service Layer Pattern
+
+Separate business logic from views:
+
+```python
+# services/article_service.py
+from django.db import transaction
+from typing import Optional
+
+class ArticleService:
+    def __init__(self):
+        self.notification_service = NotificationService()
+    
+    @transaction.atomic
+    def create_article(
+        self, 
+        author_id: int, 
+        title: str, 
+        content: str,
+        tags: list[str] = None
+    ) -> Article:
+        """Create article with full business logic."""
+        author = User.objects.get(id=author_id)
+        
+        article = Article.objects.create(
+            author=author,
+            title=title,
+            content=content,
+            slug=slugify(title)
+        )
+        
+        if tags:
+            article.tags.set(Tag.objects.filter(name__in=tags))
+        
+        # Side effects
+        self.notification_service.notify_followers(author, article)
+        
+        return article
+    
+    def publish_article(self, article_id: int) -> Article:
+        """Publish an article with validation."""
+        article = Article.objects.get(id=article_id)
+        
+        if article.status == "published":
+            raise ValueError("Article already published")
+        
+        if not article.content:
+            raise ValueError("Cannot publish empty article")
+        
+        article.status = "published"
+        article.published_at = timezone.now()
+        article.save()
+        
+        return article
+```
+
+## Repository Pattern
+
+Abstract database operations:
+
+```python
+# repositories/article_repository.py
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+class ArticleRepositoryInterface(ABC):
+    @abstractmethod
+    def get_by_id(self, id: int) -> Optional[Article]:
+        pass
+    
+    @abstractmethod
+    def get_published(self) -> List[Article]:
+        pass
+    
+    @abstractmethod
+    def save(self, article: Article) -> Article:
+        pass
+
+class DjangoArticleRepository(ArticleRepositoryInterface):
+    def get_by_id(self, id: int) -> Optional[Article]:
+        try:
+            return Article.objects.select_related("author").get(id=id)
+        except Article.DoesNotExist:
+            return None
+    
+    def get_published(self) -> List[Article]:
+        return list(
+            Article.objects
+            .filter(status="published")
+            .select_related("author")
+            .prefetch_related("tags")
+            .order_by("-published_at")
+        )
+    
+    def save(self, article: Article) -> Article:
+        article.save()
+        return article
+```
+
+## Domain Events
+
+Decouple components with events:
+
+```python
+# events/article_events.py
+from dataclasses import dataclass
+from datetime import datetime
+
+@dataclass
+class ArticlePublishedEvent:
+    article_id: int
+    author_id: int
+    published_at: datetime
+
+# events/handlers.py
+from django.dispatch import receiver
+from .signals import article_published
+
+@receiver(article_published)
+def send_notifications(sender, event: ArticlePublishedEvent, **kwargs):
+    NotificationService().notify_subscribers(event)
+
+@receiver(article_published)
+def update_search_index(sender, event: ArticlePublishedEvent, **kwargs):
+    SearchService().index_article(event.article_id)
+```
+
+## Module Structure for Large Apps
+
+```
+apps/
+├── articles/
+│   ├── __init__.py
+│   ├── admin.py
+│   ├── apps.py
+│   ├── models/
+│   │   ├── __init__.py
+│   │   ├── article.py
+│   │   └── tag.py
+│   ├── services/
+│   │   ├── __init__.py
+│   │   └── article_service.py
+│   ├── repositories/
+│   │   ├── __init__.py
+│   │   └── article_repository.py
+│   ├── api/
+│   │   ├── __init__.py
+│   │   ├── views.py
+│   │   ├── serializers.py
+│   │   └── urls.py
+│   ├── tests/
+│   │   ├── __init__.py
+│   │   ├── test_models.py
+│   │   ├── test_services.py
+│   │   └── test_api.py
+│   └── migrations/
+```
+
+## Dependency Injection
+
+```python
+# container.py
+class Container:
+    _instances = {}
+    
+    @classmethod
+    def get_article_service(cls) -> ArticleService:
+        if "article_service" not in cls._instances:
+            repo = DjangoArticleRepository()
+            notification = NotificationService()
+            cls._instances["article_service"] = ArticleService(repo, notification)
+        return cls._instances["article_service"]
+
+# views.py
+class ArticleViewSet(viewsets.ViewSet):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.service = Container.get_article_service()
+```