# egile-mcp-starter
[](https://pypi.org/project/egile-mcp-starter)
[](https://github.com/jpoullet2000/egile-mcp-starter/actions/workflows/ci.yml)
[](https://pypi.org/project/egile-mcp-starter)
[](https://github.com/jpoullet2000/egile-mcp-starter/blob/main/LICENSE)
[](https://hub.docker.com/r/jpoullet2000/egile-mcp-starter)
[](https://github.com/psf/black)
[](https://github.com/jlowin/fastmcp)
[](https://modelcontextprotocol.io/)
A comprehensive cookiecutter template for creating Model Context Protocol (MCP) servers using the FASTMCP framework.
## Features
- ๐ **Modern Python Setup**: Uses Poetry for dependency management and packaging
- ๐๏ธ **FASTMCP Framework**: Built on the efficient FASTMCP framework for MCP servers
- ๏ฟฝ **Plugin Architecture**: Extensible template system with multiple server types
- ๐ ๏ธ **Multiple Templates**: Choose from MCP, RAG, or custom templates
- ๐งช **Testing Ready**: Comprehensive test suite with pytest and coverage
- ๐ง **Development Tools**: Pre-configured with Black, Flake8, MyPy, and pre-commit hooks
- ๐ณ **Docker Support**: Optional Docker configuration for easy deployment
- ๐ **CI/CD Ready**: GitHub Actions workflows for automated testing and deployment
- ๐ **Rich Documentation**: Detailed README and code documentation
- ๐๏ธ **Configurable**: YAML-based configuration with environment variable support
## Quick Start
### Installation
```bash
# Install with pip (recommended)
pip install egile-mcp-starter
# Or use Docker
docker pull jpoullet2000/egile-mcp-starter
docker run -it jpoullet2000/egile-mcp-starter
# Or install from source
git clone https://github.com/jpoullet2000/egile-mcp-starter.git
cd egile-mcp-starter
poetry install
```
### Generate a New MCP Server
```bash
# Using the installed command (default MCP template)
egile-mcp-starter
# Or if installed from source
poetry run egile-mcp-starter
# Choose a specific template
egile-mcp-starter --template rag
# List available templates
egile-mcp-starter --list-templates
# With custom project name
egile-mcp-starter --project-name "my_custom_server"
# With multiple options
egile-mcp-starter --template rag --output-dir ./my-projects --project-name "my_rag_server" --verbose
```
### CLI Options
The `egile-mcp-starter` command supports the following options:
| Option | Short | Description | Example |
|--------|-------|-------------|---------|
| `--template` | `-t` | Choose the template to use | `--template rag` |
| `--project-name` | | Override the project name (affects directory and package name) | `--project-name "my_server"` |
| `--output-dir` | `-o` | Output directory for the generated project | `--output-dir ./projects` |
| `--list-templates` | | List all available templates and exit | `--list-templates` |
| `--verbose` | `-v` | Print detailed status information | `--verbose` |
| `--no-input` | | Don't prompt for parameters, use defaults | `--no-input` |
| `--config-file` | | Path to cookiecutter config file | `--config-file config.yaml` |
| `--default-config` | | Use default values for all template variables | `--default-config` |
| `--help` | | Show help message and exit | `--help` |
**Examples:**
```bash
# Generate with custom name and template
egile-mcp-starter --template rag --project-name "my_awesome_rag_server"
# Non-interactive generation for CI/CD
egile-mcp-starter --no-input --project-name "test_server" --output-dir ./build
# List available templates
egile-mcp-starter --list-templates
```
### Available Templates
The egile-mcp-starter uses a **plugin architecture** that supports multiple project templates. Choose the template that best fits your needs:
#### ๐ง MCP Template (default)
The standard MCP server template with comprehensive features:
- **Server Types**: Tools, resources, prompts, or full-featured servers
- **FASTMCP Integration**: Built on the efficient FASTMCP framework
- **Development Ready**: Testing, linting, CI/CD, Docker support
- **Flexible Configuration**: YAML-based config with environment variables
```bash
egile-mcp-starter --template mcp
```
#### ๐ง RAG Template
Advanced RAG-enabled MCP server with vector search capabilities:
- **Vector Databases**: Chroma, Pinecone, Weaviate, Qdrant, FAISS support
- **Embedding Models**: Sentence Transformers, OpenAI, Cohere
- **Document Processing**: PDF, DOCX, Excel, text files
- **Web Scraping**: Optional web page scraping and indexing
- **Chunking Strategies**: Recursive, semantic, fixed-size
- **Reranking**: Optional result reranking for better relevance
- **MCP Tools**: `ingest_documents`, `search_documents`, `scrape_and_index`
- **MCP Resources**: Document listing, metadata access, chunk search
```bash
egile-mcp-starter --template rag
```
#### ๐ Plugin System Features
- **Extensible**: Easy to add new templates without modifying core code
- **External Plugins**: Third-party templates via entry points
- **Template Hooks**: Pre/post-generation customization
- **Backward Compatible**: Original functionality preserved
```bash
# List all available templates
egile-mcp-starter --list-templates
# Generate with specific template and options
egile-mcp-starter --template rag --output-dir ./my-projects --project-name "my_rag_server" --verbose
```
## Generated Project Structure
The generated project will have this structure:
```
my-mcp-server/
โโโ src/
โ โโโ my_mcp_server/
โ โ โโโ __init__.py
โ โ โโโ server.py # Main MCP server implementation
โ โ โโโ config.py # Configuration management
โ โ โโโ tools/ # Tool implementations (if enabled)
โ โ โโโ resources/ # Resource handlers (if enabled)
โ โ โโโ prompts/ # Prompt templates (if enabled)
โ โ โโโ utils.py # Utility functions
โ โโโ main.py # Entry point
โโโ tests/ # Comprehensive test suite
โโโ pyproject.toml # Poetry configuration
โโโ README.md # Project documentation
โโโ Dockerfile # Docker configuration (optional)
โโโ .github/workflows/ # CI/CD workflows (optional)
```
## Extending the Plugin System
### Adding Custom Templates
The plugin architecture makes it easy to add new templates:
1. **Create a Template Plugin**:
```python
from egile_mcp_starter import TemplatePlugin
from pathlib import Path
class MyTemplatePlugin(TemplatePlugin):
def __init__(self):
super().__init__(
name="my_template",
description="My custom MCP server template",
version="1.0.0"
)
def get_template_path(self) -> Path:
return Path(__file__).parent / "my_template"
def get_default_context(self) -> dict:
return {"project_name": "My Custom Server"}
```
2. **Register the Plugin**:
```python
from egile_mcp_starter import get_registry
registry = get_registry()
registry.register(MyTemplatePlugin())
```
3. **External Plugin Distribution**:
```python
# In your package's setup.py or pyproject.toml
entry_points = {
'egile_mcp_starter.templates': [
'my_template = my_package.my_template:MyTemplatePlugin',
],
}
```
### Template Hooks
Customize the generation process with hooks:
- **Pre-generation**: Modify context, validate inputs, compute dependencies
- **Post-generation**: Initialize databases, download models, set up git repos
## Development
### Setting up Development Environment
```bash
# Clone the repository
git clone https://github.com/jpoullet2000/egile-mcp-starter.git
cd egile-mcp-starter
# Install dependencies
poetry install --with dev
# Install pre-commit hooks
poetry run pre-commit install
```
### Running Tests
```bash
# Run all tests
poetry run pytest
# Run with coverage
poetry run pytest --cov=egile_mcp_starter --cov-report=html
# Run specific tests
poetry run pytest tests/test_generator.py -v
```
### Code Quality
```bash
# Format code
poetry run black .
# Check linting
poetry run flake8 egile_mcp_starter tests
# Type checking
poetry run mypy egile_mcp_starter
# Run all pre-commit checks
poetry run pre-commit run --all-files
```
## Documentation
For detailed information about templates and the plugin system, see:
- **[Templates Guide](docs/templates.md)**: Comprehensive documentation on available templates, the plugin architecture, and how to create custom templates
- **[Configuration](docs/configuration.md)**: Detailed configuration options for each template
- **[API Reference](docs/api_reference.md)**: Complete API documentation
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`poetry run pytest`)
5. Run code quality checks (`poetry run pre-commit run --all-files`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- ๐ง Email: jpoullet2000@gmail.com
- ๐ Issues: [GitHub Issues](https://github.com/jpoullet2000/egile-mcp-starter/issues)
- ๐ MCP Documentation: [Model Context Protocol](https://modelcontextprotocol.io/)
- ๐ FASTMCP: [FASTMCP Framework](https://github.com/jlowin/fastmcp)
## Acknowledgments
- [FASTMCP](https://github.com/jlowin/fastmcp) - The amazing framework that powers the generated servers
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [Cookiecutter](https://cookiecutter.readthedocs.io/) - The templating engine
---
Built with โค๏ธ to accelerate MCP server development
Raw data
{
"_id": null,
"home_page": "https://github.com/jpoullet2000/egile-mcp-starter",
"name": "egile-mcp-starter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, fastmcp, cookiecutter, template, ai, assistant, rag, retrieval-augmented-generation, vector-database, plugin-architecture, chroma, pinecone, faiss, embedding",
"author": "Jean-Baptiste Poullet",
"author_email": "egile@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a7/f1/b188c6a05136d34199ca56558d9bc0c0eba4c640ab20fceaa4db40e6b6dd/egile_mcp_starter-0.2.0.tar.gz",
"platform": null,
"description": "# egile-mcp-starter\n\n[](https://pypi.org/project/egile-mcp-starter)\n[](https://github.com/jpoullet2000/egile-mcp-starter/actions/workflows/ci.yml)\n[](https://pypi.org/project/egile-mcp-starter)\n[](https://github.com/jpoullet2000/egile-mcp-starter/blob/main/LICENSE)\n[](https://hub.docker.com/r/jpoullet2000/egile-mcp-starter)\n[](https://github.com/psf/black)\n[](https://github.com/jlowin/fastmcp)\n[](https://modelcontextprotocol.io/)\n\nA comprehensive cookiecutter template for creating Model Context Protocol (MCP) servers using the FASTMCP framework.\n\n## Features\n\n- \ud83d\ude80 **Modern Python Setup**: Uses Poetry for dependency management and packaging\n- \ud83c\udfd7\ufe0f **FASTMCP Framework**: Built on the efficient FASTMCP framework for MCP servers\n- \ufffd **Plugin Architecture**: Extensible template system with multiple server types\n- \ud83d\udee0\ufe0f **Multiple Templates**: Choose from MCP, RAG, or custom templates\n- \ud83e\uddea **Testing Ready**: Comprehensive test suite with pytest and coverage\n- \ud83d\udd27 **Development Tools**: Pre-configured with Black, Flake8, MyPy, and pre-commit hooks\n- \ud83d\udc33 **Docker Support**: Optional Docker configuration for easy deployment\n- \ud83d\udd04 **CI/CD Ready**: GitHub Actions workflows for automated testing and deployment\n- \ud83d\udcda **Rich Documentation**: Detailed README and code documentation\n- \ud83c\udf9b\ufe0f **Configurable**: YAML-based configuration with environment variable support\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install with pip (recommended)\npip install egile-mcp-starter\n\n# Or use Docker\ndocker pull jpoullet2000/egile-mcp-starter\ndocker run -it jpoullet2000/egile-mcp-starter\n\n# Or install from source\ngit clone https://github.com/jpoullet2000/egile-mcp-starter.git\ncd egile-mcp-starter\npoetry install\n```\n\n### Generate a New MCP Server\n\n```bash\n# Using the installed command (default MCP template)\negile-mcp-starter\n\n# Or if installed from source\npoetry run egile-mcp-starter\n\n# Choose a specific template\negile-mcp-starter --template rag\n\n# List available templates\negile-mcp-starter --list-templates\n\n# With custom project name\negile-mcp-starter --project-name \"my_custom_server\"\n\n# With multiple options\negile-mcp-starter --template rag --output-dir ./my-projects --project-name \"my_rag_server\" --verbose\n```\n\n### CLI Options\n\nThe `egile-mcp-starter` command supports the following options:\n\n| Option | Short | Description | Example |\n|--------|-------|-------------|---------|\n| `--template` | `-t` | Choose the template to use | `--template rag` |\n| `--project-name` | | Override the project name (affects directory and package name) | `--project-name \"my_server\"` |\n| `--output-dir` | `-o` | Output directory for the generated project | `--output-dir ./projects` |\n| `--list-templates` | | List all available templates and exit | `--list-templates` |\n| `--verbose` | `-v` | Print detailed status information | `--verbose` |\n| `--no-input` | | Don't prompt for parameters, use defaults | `--no-input` |\n| `--config-file` | | Path to cookiecutter config file | `--config-file config.yaml` |\n| `--default-config` | | Use default values for all template variables | `--default-config` |\n| `--help` | | Show help message and exit | `--help` |\n\n**Examples:**\n\n```bash\n# Generate with custom name and template\negile-mcp-starter --template rag --project-name \"my_awesome_rag_server\"\n\n# Non-interactive generation for CI/CD\negile-mcp-starter --no-input --project-name \"test_server\" --output-dir ./build\n\n# List available templates\negile-mcp-starter --list-templates\n```\n\n### Available Templates\n\nThe egile-mcp-starter uses a **plugin architecture** that supports multiple project templates. Choose the template that best fits your needs:\n\n#### \ud83d\udd27 MCP Template (default)\nThe standard MCP server template with comprehensive features:\n- **Server Types**: Tools, resources, prompts, or full-featured servers\n- **FASTMCP Integration**: Built on the efficient FASTMCP framework\n- **Development Ready**: Testing, linting, CI/CD, Docker support\n- **Flexible Configuration**: YAML-based config with environment variables\n\n```bash\negile-mcp-starter --template mcp\n```\n\n#### \ud83e\udde0 RAG Template\nAdvanced RAG-enabled MCP server with vector search capabilities:\n- **Vector Databases**: Chroma, Pinecone, Weaviate, Qdrant, FAISS support\n- **Embedding Models**: Sentence Transformers, OpenAI, Cohere\n- **Document Processing**: PDF, DOCX, Excel, text files\n- **Web Scraping**: Optional web page scraping and indexing\n- **Chunking Strategies**: Recursive, semantic, fixed-size\n- **Reranking**: Optional result reranking for better relevance\n- **MCP Tools**: `ingest_documents`, `search_documents`, `scrape_and_index`\n- **MCP Resources**: Document listing, metadata access, chunk search\n\n```bash\negile-mcp-starter --template rag\n```\n\n#### \ud83d\udd0c Plugin System Features\n- **Extensible**: Easy to add new templates without modifying core code\n- **External Plugins**: Third-party templates via entry points\n- **Template Hooks**: Pre/post-generation customization\n- **Backward Compatible**: Original functionality preserved\n\n```bash\n# List all available templates\negile-mcp-starter --list-templates\n\n# Generate with specific template and options\negile-mcp-starter --template rag --output-dir ./my-projects --project-name \"my_rag_server\" --verbose\n```\n\n## Generated Project Structure\n\nThe generated project will have this structure:\n\n```\nmy-mcp-server/\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 my_mcp_server/\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 server.py # Main MCP server implementation\n\u2502 \u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u2502 \u251c\u2500\u2500 tools/ # Tool implementations (if enabled)\n\u2502 \u2502 \u251c\u2500\u2500 resources/ # Resource handlers (if enabled)\n\u2502 \u2502 \u251c\u2500\u2500 prompts/ # Prompt templates (if enabled)\n\u2502 \u2502 \u2514\u2500\u2500 utils.py # Utility functions\n\u2502 \u2514\u2500\u2500 main.py # Entry point\n\u251c\u2500\u2500 tests/ # Comprehensive test suite\n\u251c\u2500\u2500 pyproject.toml # Poetry configuration\n\u251c\u2500\u2500 README.md # Project documentation\n\u251c\u2500\u2500 Dockerfile # Docker configuration (optional)\n\u2514\u2500\u2500 .github/workflows/ # CI/CD workflows (optional)\n```\n\n## Extending the Plugin System\n\n### Adding Custom Templates\n\nThe plugin architecture makes it easy to add new templates:\n\n1. **Create a Template Plugin**:\n```python\nfrom egile_mcp_starter import TemplatePlugin\nfrom pathlib import Path\n\nclass MyTemplatePlugin(TemplatePlugin):\n def __init__(self):\n super().__init__(\n name=\"my_template\",\n description=\"My custom MCP server template\",\n version=\"1.0.0\"\n )\n \n def get_template_path(self) -> Path:\n return Path(__file__).parent / \"my_template\"\n \n def get_default_context(self) -> dict:\n return {\"project_name\": \"My Custom Server\"}\n```\n\n2. **Register the Plugin**:\n```python\nfrom egile_mcp_starter import get_registry\n\nregistry = get_registry()\nregistry.register(MyTemplatePlugin())\n```\n\n3. **External Plugin Distribution**:\n```python\n# In your package's setup.py or pyproject.toml\nentry_points = {\n 'egile_mcp_starter.templates': [\n 'my_template = my_package.my_template:MyTemplatePlugin',\n ],\n}\n```\n\n### Template Hooks\n\nCustomize the generation process with hooks:\n- **Pre-generation**: Modify context, validate inputs, compute dependencies\n- **Post-generation**: Initialize databases, download models, set up git repos\n\n## Development\n\n### Setting up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/jpoullet2000/egile-mcp-starter.git\ncd egile-mcp-starter\n\n# Install dependencies\npoetry install --with dev\n\n# Install pre-commit hooks\npoetry run pre-commit install\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov=egile_mcp_starter --cov-report=html\n\n# Run specific tests\npoetry run pytest tests/test_generator.py -v\n```\n\n### Code Quality\n\n```bash\n# Format code\npoetry run black .\n\n# Check linting\npoetry run flake8 egile_mcp_starter tests\n\n# Type checking\npoetry run mypy egile_mcp_starter\n\n# Run all pre-commit checks\npoetry run pre-commit run --all-files\n```\n\n## Documentation\n\nFor detailed information about templates and the plugin system, see:\n\n- **[Templates Guide](docs/templates.md)**: Comprehensive documentation on available templates, the plugin architecture, and how to create custom templates\n- **[Configuration](docs/configuration.md)**: Detailed configuration options for each template\n- **[API Reference](docs/api_reference.md)**: Complete API documentation\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`poetry run pytest`)\n5. Run code quality checks (`poetry run pre-commit run --all-files`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. 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## Support\n\n- \ud83d\udce7 Email: jpoullet2000@gmail.com\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/jpoullet2000/egile-mcp-starter/issues)\n- \ud83d\udcd6 MCP Documentation: [Model Context Protocol](https://modelcontextprotocol.io/)\n- \ud83d\ude80 FASTMCP: [FASTMCP Framework](https://github.com/jlowin/fastmcp)\n\n## Acknowledgments\n\n- [FASTMCP](https://github.com/jlowin/fastmcp) - The amazing framework that powers the generated servers\n- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification\n- [Cookiecutter](https://cookiecutter.readthedocs.io/) - The templating engine\n\n---\n\nBuilt with \u2764\ufe0f to accelerate MCP server development\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive and extensible cookiecutter template system for creating Model Context Protocol (MCP) servers with plugin architecture supporting multiple templates including RAG-enabled servers",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/jpoullet2000/egile-mcp-starter",
"Homepage": "https://github.com/jpoullet2000/egile-mcp-starter",
"Repository": "https://github.com/jpoullet2000/egile-mcp-starter"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" fastmcp",
" cookiecutter",
" template",
" ai",
" assistant",
" rag",
" retrieval-augmented-generation",
" vector-database",
" plugin-architecture",
" chroma",
" pinecone",
" faiss",
" embedding"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f92b73d9c8cca6ee14d1917f5d378e748a9e4dc99d58c388e4e7be805d395a3",
"md5": "ee6ed27041fd55f325109398f78303fb",
"sha256": "884cef6f55e76b5ba149c4473ef9481e7a1f4c934e9b05ff06e3a6679637ee3a"
},
"downloads": -1,
"filename": "egile_mcp_starter-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee6ed27041fd55f325109398f78303fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 66252,
"upload_time": "2025-07-29T14:31:32",
"upload_time_iso_8601": "2025-07-29T14:31:32.367126Z",
"url": "https://files.pythonhosted.org/packages/8f/92/b73d9c8cca6ee14d1917f5d378e748a9e4dc99d58c388e4e7be805d395a3/egile_mcp_starter-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a7f1b188c6a05136d34199ca56558d9bc0c0eba4c640ab20fceaa4db40e6b6dd",
"md5": "b8a0ccab23c30bf8dcc51a86637b3c9a",
"sha256": "dd415459848a89d11bbffff5611ab0cbebb94d307c284b7f7e1ce9686d037c58"
},
"downloads": -1,
"filename": "egile_mcp_starter-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b8a0ccab23c30bf8dcc51a86637b3c9a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 47773,
"upload_time": "2025-07-29T14:31:33",
"upload_time_iso_8601": "2025-07-29T14:31:33.734817Z",
"url": "https://files.pythonhosted.org/packages/a7/f1/b188c6a05136d34199ca56558d9bc0c0eba4c640ab20fceaa4db40e6b6dd/egile_mcp_starter-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 14:31:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jpoullet2000",
"github_project": "egile-mcp-starter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "egile-mcp-starter"
}
JSON
