# ArchGuide MCP Server
A Python-based Model Context Protocol (MCP) server that provides architecture guidelines, design patterns, and best practices directly into AI development workflows. Built with modern Python tooling including FastMCP, Pydantic, and uv.
## Features
- **Architecture Guidelines**: Comprehensive guidelines for various architectural patterns
- **Smart Search**: Full-text search across all guidelines and patterns using Whoosh
- **Context-Aware**: Filter guidelines based on tech stack, scale, and domain
- **Version Control**: Support for multiple versions of guidelines
- **Compliance Checking**: Validate designs against architectural standards
- **Fast & Efficient**: In-memory caching and optimized search
- **Modern Python**: Built with FastMCP, Pydantic, and uv package manager
## Installation
### Prerequisites
- Python 3.12+
- uv package manager ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
### Install from Source
```bash
git clone https://github.com/yourusername/archguide-mcp-python.git
cd archguide-mcp-python
uv sync
```
### Development Setup
```bash
# Install with development dependencies
uv sync --dev
# Run tests
uv run python -m pytest
# Run the server
uv run archguide-mcp
```
## Usage with Claude Code
1. **Add to your Claude Code configuration**:
```json
{
"mcpServers": {
"archguide": {
"command": "uv",
"args": ["run", "archguide-mcp"],
"cwd": "/path/to/archguide-mcp-python",
"env": {
"GUIDELINES_PATH": "/path/to/your/guidelines"
}
}
}
}
```
2. **Use in your prompts**:
```
Design a microservices architecture for an e-commerce platform. use archguide
Show me the event sourcing pattern with examples. use archguide
Check if this API design follows our REST guidelines. use archguide
What are the best practices for authentication in Python FastAPI apps? use archguide
```
## Available MCP Tools
### `get-architecture-guideline`
Fetch architecture guidelines for a specific topic with optional context filtering.
**Parameters**:
- `topic` (required): Architecture topic (e.g., "microservices", "api-design", "security")
- `context` (optional): Additional filtering context
- `tech_stack`: Technology stack (e.g., ["python", "fastapi"])
- `scale`: System scale ("startup", "growth", "enterprise")
- `domain`: Business domain (e.g., "e-commerce", "fintech")
- `version` (optional): Specific version of guidelines
- `include_examples` (optional): Include code examples (default: true)
### `search-patterns`
Search for architecture patterns, best practices, and solutions.
**Parameters**:
- `query` (required): Search query
- `filters` (optional): Search filters
- `category`: Filter by category
- `tags`: Filter by tags
- `tech_stack`: Filter by technology stack
- `limit` (optional): Maximum results (default: 10)
### `list-categories`
List all available architecture guideline categories.
### `check-compliance`
Check if a design or code snippet complies with architecture guidelines.
**Parameters**:
- `design` (required): Design description or code snippet
- `guidelines` (optional): Specific guideline IDs to check against
### `get-server-stats`
Get statistics about the ArchGuide server including guideline counts and categories.
### Dynamic Guideline Management Tools ✨
#### `add-guideline`
Add a new architecture guideline dynamically during your Claude Code session.
**Parameters**:
- `title` (required): Title of the guideline
- `category` (required): Category (e.g., "microservices", "security", "cloud-native")
- `content` (required): Main content in markdown format
- `subcategory` (optional): Subcategory for organization
- `tags` (optional): List of tags for categorization
- `patterns` (optional): List of patterns with keys: name, description, when, implementation, consequences
- `anti_patterns` (optional): List of anti-patterns with keys: name, description, why, instead
- `examples` (optional): List of code examples with keys: title, description, language, code
- `tech_stack` (optional): Applicable technology stack
- `applicability` (optional): Contexts where this applies (e.g., ['startup', 'enterprise'])
- `author` (optional): Author name (default: "Claude Code User")
**Example Usage**:
```
Add a new guideline about API rate limiting patterns for microservices with examples in Python and Go
```
#### `update-guideline`
Update an existing architecture guideline.
**Parameters**:
- `guideline_id` (required): ID of the guideline to update
- `title` (optional): New title
- `content` (optional): New content
- `tags` (optional): New tags
- `patterns` (optional): New patterns list
- `anti_patterns` (optional): New anti-patterns list
- `examples` (optional): New examples list
#### `delete-guideline`
Delete an architecture guideline.
**Parameters**:
- `guideline_id` (required): ID of the guideline to delete
#### `reload-guidelines`
Reload all guidelines from the filesystem to pick up any manual changes made to .md files.
## Dynamic Guideline Creation Examples
With the new dynamic management tools, you can create guidelines on-the-fly during your development workflow:
### Example 1: Create a Performance Guideline
```
Add a new guideline titled "Database Query Optimization" in the "performance" category with content about N+1 queries, including patterns for eager loading and anti-patterns for sequential queries
```
### Example 2: Update Existing Guideline
```
Update the guideline "microservices-data-management" to add a new pattern about distributed transactions using the Saga pattern
```
### Example 3: Create Team-Specific Guidelines
```
Add a guideline about our team's specific React component patterns with examples showing our custom hooks and state management conventions
```
## Writing Guidelines
Guidelines are written in Markdown with YAML frontmatter:
```markdown
---
id: unique-guideline-id
title: Guideline Title
category: main-category
subcategory: sub-category
tags: [tag1, tag2, tag3]
version: 1.0.0
author: Your Name
created: 2024-01-01
lastUpdated: 2024-01-02
applicability: [startup, enterprise, cloud-native]
techStack: [python, fastapi, postgresql]
prerequisites: [http-basics, api-design]
relatedGuidelines: [other-guideline-id]
---
# Guideline Content
Your guideline content here...
## Pattern: Pattern Name
### Description
Pattern description.
### When to use
When to use this pattern.
### Implementation
How to implement.
### Consequences
- Positive consequence
- Negative consequence
## Anti-pattern: Anti-pattern Name
### Description
Anti-pattern description.
### Why it's bad
Why this is problematic.
### Instead
What to do instead.
### Example: Code Example
Description of the example.
```python
def example_function():
return "Hello, World!"
```
```
## Project Structure
```
archguide-mcp-python/
├── src/
│ └── archguide_mcp_python/
│ ├── __init__.py # Package initialization
│ ├── server.py # FastMCP server implementation
│ ├── models/
│ │ └── types.py # Pydantic data models
│ ├── storage/
│ │ ├── store.py # Main guideline store
│ │ ├── filesystem.py # File-based storage
│ │ └── search.py # Whoosh search index
│ ├── parsers/
│ │ └── content.py # Markdown content parser
│ └── utils/
│ ├── cache.py # Caching utilities
│ └── formatters.py # Output formatting
├── guidelines/ # Architecture guidelines content
│ ├── microservices/
│ ├── cloud-native/
│ ├── security/
│ └── data-patterns/
├── tests/ # Test suite
├── pyproject.toml # Project configuration
└── README.md
```
## Configuration
### Environment Variables
- `GUIDELINES_PATH`: Path to guidelines directory (default: `./guidelines`)
- `INDEX_DIR`: Path to search index directory (optional)
- `CACHE_TTL`: Cache time-to-live in seconds (default: 300)
### Guidelines Directory Structure
```
guidelines/
├── microservices/
│ ├── data-management.md
│ └── communication-patterns.md
├── cloud-native/
│ ├── api-design.md
│ └── containerization.md
├── security/
│ ├── authentication.md
│ └── authorization.md
└── data-patterns/
├── database-design.md
└── caching-strategies.md
```
## Development
### Running Tests
```bash
# Run all tests
uv run python -m pytest
# Run specific test file
uv run python -m pytest tests/test_cache.py -v
# Run with coverage
uv run python -m pytest --cov=archguide_mcp_python
```
### Code Quality
```bash
# Format code
uv run black src/ tests/
# Lint code
uv run ruff check src/ tests/
# Type checking
uv run mypy src/
```
### Adding New Guidelines
1. Create a new markdown file in the appropriate category directory
2. Follow the guideline template with proper frontmatter
3. Include patterns, anti-patterns, and examples as needed
4. Restart the server to load new guidelines
## Sample Guidelines Included
The project includes sample guidelines for:
- **Microservices**: Data management patterns, event sourcing, database per service
- **Cloud-Native APIs**: RESTful design, versioning, status codes
- **Security**: Authentication patterns, JWT, OAuth2, RBAC
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Write guidelines in the appropriate category
4. Add tests for new functionality
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built with [FastMCP](https://github.com/jlowin/fastmcp) for MCP server functionality
- Uses [Whoosh](https://whoosh.readthedocs.io/) for full-text search
- Powered by [Pydantic](https://pydantic.dev/) for data validation
- Package management by [uv](https://github.com/astral-sh/uv)
---
**ArchGuide MCP Server** - Making architectural knowledge instantly accessible within AI development workflows.
Raw data
{
"_id": null,
"home_page": null,
"name": "archguide-mcp-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Ioan Salau <salauioan@yahoo.com>",
"keywords": "ai, architecture, best-practices, claude, design-patterns, fastmcp, guidelines, mcp, microservices, patterns, software-architecture",
"author": null,
"author_email": "Ioan Salau <salauioan@yahoo.com>",
"download_url": "https://files.pythonhosted.org/packages/01/ce/f04912fa879c6a1add8066b2a920152ececc89d35a88414e85dc6652f094/archguide_mcp_python-0.2.1.tar.gz",
"platform": null,
"description": "# ArchGuide MCP Server\n\nA Python-based Model Context Protocol (MCP) server that provides architecture guidelines, design patterns, and best practices directly into AI development workflows. Built with modern Python tooling including FastMCP, Pydantic, and uv.\n\n## Features\n\n- **Architecture Guidelines**: Comprehensive guidelines for various architectural patterns\n- **Smart Search**: Full-text search across all guidelines and patterns using Whoosh\n- **Context-Aware**: Filter guidelines based on tech stack, scale, and domain\n- **Version Control**: Support for multiple versions of guidelines\n- **Compliance Checking**: Validate designs against architectural standards\n- **Fast & Efficient**: In-memory caching and optimized search\n- **Modern Python**: Built with FastMCP, Pydantic, and uv package manager\n\n## Installation\n\n### Prerequisites\n\n- Python 3.12+\n- uv package manager ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))\n\n### Install from Source\n\n```bash\ngit clone https://github.com/yourusername/archguide-mcp-python.git\ncd archguide-mcp-python\nuv sync\n```\n\n### Development Setup\n\n```bash\n# Install with development dependencies\nuv sync --dev\n\n# Run tests\nuv run python -m pytest\n\n# Run the server\nuv run archguide-mcp\n```\n\n## Usage with Claude Code\n\n1. **Add to your Claude Code configuration**:\n\n```json\n{\n \"mcpServers\": {\n \"archguide\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"archguide-mcp\"],\n \"cwd\": \"/path/to/archguide-mcp-python\",\n \"env\": {\n \"GUIDELINES_PATH\": \"/path/to/your/guidelines\"\n }\n }\n }\n}\n```\n\n2. **Use in your prompts**:\n\n```\nDesign a microservices architecture for an e-commerce platform. use archguide\n\nShow me the event sourcing pattern with examples. use archguide\n\nCheck if this API design follows our REST guidelines. use archguide\n\nWhat are the best practices for authentication in Python FastAPI apps? use archguide\n```\n\n## Available MCP Tools\n\n### `get-architecture-guideline`\nFetch architecture guidelines for a specific topic with optional context filtering.\n\n**Parameters**:\n- `topic` (required): Architecture topic (e.g., \"microservices\", \"api-design\", \"security\")\n- `context` (optional): Additional filtering context\n - `tech_stack`: Technology stack (e.g., [\"python\", \"fastapi\"])\n - `scale`: System scale (\"startup\", \"growth\", \"enterprise\")\n - `domain`: Business domain (e.g., \"e-commerce\", \"fintech\")\n- `version` (optional): Specific version of guidelines\n- `include_examples` (optional): Include code examples (default: true)\n\n### `search-patterns`\nSearch for architecture patterns, best practices, and solutions.\n\n**Parameters**:\n- `query` (required): Search query\n- `filters` (optional): Search filters\n - `category`: Filter by category\n - `tags`: Filter by tags\n - `tech_stack`: Filter by technology stack\n- `limit` (optional): Maximum results (default: 10)\n\n### `list-categories`\nList all available architecture guideline categories.\n\n### `check-compliance`\nCheck if a design or code snippet complies with architecture guidelines.\n\n**Parameters**:\n- `design` (required): Design description or code snippet\n- `guidelines` (optional): Specific guideline IDs to check against\n\n### `get-server-stats`\nGet statistics about the ArchGuide server including guideline counts and categories.\n\n### Dynamic Guideline Management Tools \u2728\n\n#### `add-guideline`\nAdd a new architecture guideline dynamically during your Claude Code session.\n\n**Parameters**:\n- `title` (required): Title of the guideline\n- `category` (required): Category (e.g., \"microservices\", \"security\", \"cloud-native\")\n- `content` (required): Main content in markdown format\n- `subcategory` (optional): Subcategory for organization\n- `tags` (optional): List of tags for categorization\n- `patterns` (optional): List of patterns with keys: name, description, when, implementation, consequences\n- `anti_patterns` (optional): List of anti-patterns with keys: name, description, why, instead\n- `examples` (optional): List of code examples with keys: title, description, language, code\n- `tech_stack` (optional): Applicable technology stack\n- `applicability` (optional): Contexts where this applies (e.g., ['startup', 'enterprise'])\n- `author` (optional): Author name (default: \"Claude Code User\")\n\n**Example Usage**:\n```\nAdd a new guideline about API rate limiting patterns for microservices with examples in Python and Go\n```\n\n#### `update-guideline`\nUpdate an existing architecture guideline.\n\n**Parameters**:\n- `guideline_id` (required): ID of the guideline to update\n- `title` (optional): New title\n- `content` (optional): New content\n- `tags` (optional): New tags\n- `patterns` (optional): New patterns list\n- `anti_patterns` (optional): New anti-patterns list\n- `examples` (optional): New examples list\n\n#### `delete-guideline`\nDelete an architecture guideline.\n\n**Parameters**:\n- `guideline_id` (required): ID of the guideline to delete\n\n#### `reload-guidelines`\nReload all guidelines from the filesystem to pick up any manual changes made to .md files.\n\n## Dynamic Guideline Creation Examples\n\nWith the new dynamic management tools, you can create guidelines on-the-fly during your development workflow:\n\n### Example 1: Create a Performance Guideline\n```\nAdd a new guideline titled \"Database Query Optimization\" in the \"performance\" category with content about N+1 queries, including patterns for eager loading and anti-patterns for sequential queries\n```\n\n### Example 2: Update Existing Guideline\n```\nUpdate the guideline \"microservices-data-management\" to add a new pattern about distributed transactions using the Saga pattern\n```\n\n### Example 3: Create Team-Specific Guidelines\n```\nAdd a guideline about our team's specific React component patterns with examples showing our custom hooks and state management conventions\n```\n\n## Writing Guidelines\n\nGuidelines are written in Markdown with YAML frontmatter:\n\n```markdown\n---\nid: unique-guideline-id\ntitle: Guideline Title\ncategory: main-category\nsubcategory: sub-category\ntags: [tag1, tag2, tag3]\nversion: 1.0.0\nauthor: Your Name\ncreated: 2024-01-01\nlastUpdated: 2024-01-02\napplicability: [startup, enterprise, cloud-native]\ntechStack: [python, fastapi, postgresql]\nprerequisites: [http-basics, api-design]\nrelatedGuidelines: [other-guideline-id]\n---\n\n# Guideline Content\n\nYour guideline content here...\n\n## Pattern: Pattern Name\n\n### Description\nPattern description.\n\n### When to use\nWhen to use this pattern.\n\n### Implementation\nHow to implement.\n\n### Consequences\n- Positive consequence\n- Negative consequence\n\n## Anti-pattern: Anti-pattern Name\n\n### Description\nAnti-pattern description.\n\n### Why it's bad\nWhy this is problematic.\n\n### Instead\nWhat to do instead.\n\n### Example: Code Example\nDescription of the example.\n\n```python\ndef example_function():\n return \"Hello, World!\"\n```\n```\n\n## Project Structure\n\n```\narchguide-mcp-python/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 archguide_mcp_python/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 server.py # FastMCP server implementation\n\u2502 \u251c\u2500\u2500 models/\n\u2502 \u2502 \u2514\u2500\u2500 types.py # Pydantic data models\n\u2502 \u251c\u2500\u2500 storage/\n\u2502 \u2502 \u251c\u2500\u2500 store.py # Main guideline store\n\u2502 \u2502 \u251c\u2500\u2500 filesystem.py # File-based storage\n\u2502 \u2502 \u2514\u2500\u2500 search.py # Whoosh search index\n\u2502 \u251c\u2500\u2500 parsers/\n\u2502 \u2502 \u2514\u2500\u2500 content.py # Markdown content parser\n\u2502 \u2514\u2500\u2500 utils/\n\u2502 \u251c\u2500\u2500 cache.py # Caching utilities\n\u2502 \u2514\u2500\u2500 formatters.py # Output formatting\n\u251c\u2500\u2500 guidelines/ # Architecture guidelines content\n\u2502 \u251c\u2500\u2500 microservices/\n\u2502 \u251c\u2500\u2500 cloud-native/\n\u2502 \u251c\u2500\u2500 security/\n\u2502 \u2514\u2500\u2500 data-patterns/\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md\n```\n\n## Configuration\n\n### Environment Variables\n\n- `GUIDELINES_PATH`: Path to guidelines directory (default: `./guidelines`)\n- `INDEX_DIR`: Path to search index directory (optional)\n- `CACHE_TTL`: Cache time-to-live in seconds (default: 300)\n\n### Guidelines Directory Structure\n\n```\nguidelines/\n\u251c\u2500\u2500 microservices/\n\u2502 \u251c\u2500\u2500 data-management.md\n\u2502 \u2514\u2500\u2500 communication-patterns.md\n\u251c\u2500\u2500 cloud-native/\n\u2502 \u251c\u2500\u2500 api-design.md\n\u2502 \u2514\u2500\u2500 containerization.md\n\u251c\u2500\u2500 security/\n\u2502 \u251c\u2500\u2500 authentication.md\n\u2502 \u2514\u2500\u2500 authorization.md\n\u2514\u2500\u2500 data-patterns/\n \u251c\u2500\u2500 database-design.md\n \u2514\u2500\u2500 caching-strategies.md\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run python -m pytest\n\n# Run specific test file\nuv run python -m pytest tests/test_cache.py -v\n\n# Run with coverage\nuv run python -m pytest --cov=archguide_mcp_python\n```\n\n### Code Quality\n\n```bash\n# Format code\nuv run black src/ tests/\n\n# Lint code\nuv run ruff check src/ tests/\n\n# Type checking\nuv run mypy src/\n```\n\n### Adding New Guidelines\n\n1. Create a new markdown file in the appropriate category directory\n2. Follow the guideline template with proper frontmatter\n3. Include patterns, anti-patterns, and examples as needed\n4. Restart the server to load new guidelines\n\n## Sample Guidelines Included\n\nThe project includes sample guidelines for:\n\n- **Microservices**: Data management patterns, event sourcing, database per service\n- **Cloud-Native APIs**: RESTful design, versioning, status codes\n- **Security**: Authentication patterns, JWT, OAuth2, RBAC\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Write guidelines in the appropriate category\n4. Add tests for new functionality\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [FastMCP](https://github.com/jlowin/fastmcp) for MCP server functionality\n- Uses [Whoosh](https://whoosh.readthedocs.io/) for full-text search\n- Powered by [Pydantic](https://pydantic.dev/) for data validation\n- Package management by [uv](https://github.com/astral-sh/uv)\n\n---\n\n**ArchGuide MCP Server** - Making architectural knowledge instantly accessible within AI development workflows.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Architecture Guidelines MCP Server - Inject architectural best practices into AI workflows",
"version": "0.2.1",
"project_urls": {
"Bug Reports": "https://github.com/ioansalau/archguide-mcp-python/issues",
"Documentation": "https://github.com/ioansalau/archguide-mcp-python#readme",
"Homepage": "https://github.com/ioansalau/archguide-mcp-python",
"Source": "https://github.com/ioansalau/archguide-mcp-python"
},
"split_keywords": [
"ai",
" architecture",
" best-practices",
" claude",
" design-patterns",
" fastmcp",
" guidelines",
" mcp",
" microservices",
" patterns",
" software-architecture"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d62cbac97613cfaf4c88c77c57d1639ed9cd1f65e08fcaf7925e38f2abbf5cde",
"md5": "6eac0d3d8bc4d273e6610ebe0761717f",
"sha256": "8efac9b3a8b05bdc4372671c69f96f79c4eb2057d6b967c89b08ad963b300a8e"
},
"downloads": -1,
"filename": "archguide_mcp_python-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6eac0d3d8bc4d273e6610ebe0761717f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 24767,
"upload_time": "2025-07-26T15:01:47",
"upload_time_iso_8601": "2025-07-26T15:01:47.084056Z",
"url": "https://files.pythonhosted.org/packages/d6/2c/bac97613cfaf4c88c77c57d1639ed9cd1f65e08fcaf7925e38f2abbf5cde/archguide_mcp_python-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "01cef04912fa879c6a1add8066b2a920152ececc89d35a88414e85dc6652f094",
"md5": "63fb441f66ca4356275a006b76da5179",
"sha256": "dcf1796564f555ed856754c41c432cc0a919ef83a72a5891dc166936c003285f"
},
"downloads": -1,
"filename": "archguide_mcp_python-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "63fb441f66ca4356275a006b76da5179",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 90204,
"upload_time": "2025-07-26T15:01:47",
"upload_time_iso_8601": "2025-07-26T15:01:47.973464Z",
"url": "https://files.pythonhosted.org/packages/01/ce/f04912fa879c6a1add8066b2a920152ececc89d35a88414e85dc6652f094/archguide_mcp_python-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 15:01:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ioansalau",
"github_project": "archguide-mcp-python",
"github_not_found": true,
"lcname": "archguide-mcp-python"
}
JSON
