jaraco-website-mcp-server 1.0.0__tar.gz

jaraco_website_mcp_server-1.0.0/PKG-INFO

@@ -0,0 +1,442 @@
+Metadata-Version: 2.4
+Name: jaraco-website-mcp-server
+Version: 1.0.0
+Summary: MCP Server for Jaraco GmbH website - provides programmatic access to blog posts, services, and categories
+Author-email: Jaraco GmbH <info@jaraco.de>
+License: MIT
+Project-URL: Homepage, https://jarakube.eu/mcp-server/mcp-server.html
+Project-URL: Documentation, https://jarakube.eu/mcp-server/mcp-server.html
+Project-URL: Repository, https://github.com/jaracogmbh/jarakube-jaraco-app/tree/develop/jarasite-website/mcp_server
+Project-URL: Issues, https://github.com/jaracogmbh/jarakube-jaraco-app/issues
+Keywords: mcp,model-context-protocol,jaraco,website,api
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=2.2.0
+Requires-Dist: fastmcp>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+
+<!-- mcp-name: io.github.jaracogmbh/jaraco-website -->
+
+# Jaraco Website MCP Server
+
+This directory contains the MCP (Model Context Protocol) server implementation for the Jaraco website. The server provides programmatic access to website content including blog posts, services, and categories, with read-only access and email drafting capabilities.
+
+## Features
+
+- **Read Blog Posts**: Access all blog posts in multiple languages (EN, DE, FR, ES, NL)
+- **Read Services**: Access all service descriptions and details
+- **Browse Categories**: Explore content organized by categories
+- **Draft Emails**: Generate service-specific email templates with appropriate default text
+- **Read-Only Access**: All content access is read-only
+- **Multi-Language Support**: All content available in 5 languages
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.10 or higher (required for MCP SDK v2)
+- pip package manager
+
+### Installation
+
+1. Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+2. Run the server:
+
+```bash
+python -m mcp_server.server
+```
+
+The server will start on `localhost:8081` by default with the `/mcp` endpoint.
+
+### Test the Server
+
+You can test the server using curl or any MCP client:
+
+```bash
+# List all resources
+curl http://localhost:8081/mcp -X POST -H "Content-Type: application/json" -d '{"method": "list_resources"}'
+
+# Read a specific blog post  
+curl http://localhost:8081/mcp -X POST -H "Content-Type: application/json" -d '{"method": "read_resource", "params": {"uri": "blog_posts/from-data-chaos-to-efficient-automation"}}'
+
+# Or use the MCP CLI (if installed)
+mcp dev mcp_server.server
+```
+
+## Configuration
+
+The server can be configured using environment variables. In MCP SDK v2, transport settings are passed to the `run()` method, but can still be configured via environment variables for convenience.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_HOST` | `0.0.0.0` | Host to bind to (used by run()) |
+| `MCP_PORT` | `8081` | Port to listen on (used by run()) |
+| `CONTENT_ROOT` | Project root | Root directory for website content |
+| `CACHE_ENABLED` | `true` | Enable content caching |
+| `CACHE_TTL` | `300` | Cache time-to-live in seconds |
+| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
+
+Example:
+
+```bash
+# Configure via environment variables
+MCP_PORT=9090 CONTENT_ROOT=/path/to/content LOG_LEVEL=DEBUG python -m mcp_server.server
+
+# Or use default configuration
+python -m mcp_server.server
+```
+
+### Transport Configuration
+
+The server uses **Streamable HTTP transport** by default, which is the recommended transport for MCP v2. The endpoint will be available at:
+- `http://localhost:8081/mcp`
+
+For production deployments behind a proxy, you may need to configure transport security settings.
+
+## Docker
+
+### Build the Image
+
+```bash
+docker build -t jaraco-mcp-server -f mcp_server/Dockerfile .
+```
+
+### Run the Container
+
+```bash
+docker run -p 8081:8081 -v $(pwd):/app jaraco-mcp-server
+```
+
+### Docker Compose
+
+Add to your `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  mcp-server:
+    build:
+      context: .
+      dockerfile: mcp_server/Dockerfile
+    ports:
+      - "8081:8081"
+    volumes:
+      - .:/app
+    environment:
+      - MCP_PORT=8081
+      - CONTENT_ROOT=/app
+      - LOG_LEVEL=INFO
+    restart: unless-stopped
+```
+
+## Usage Examples
+
+### Python Client
+
+```python
+from mcp.client import Client
+
+async def main():
+    client = Client("jaraco-website", url="http://localhost:8081")
+    await client.connect()
+    
+    # List all resources
+    resources = await client.list_resources()
+    print(f"Found {len(resources)} resources")
+    
+    # Read a blog post
+    post = await client.read_resource("blog_posts/from-data-chaos-to-efficient-automation")
+    print(post)
+    
+    # Draft an email
+    email = await client.call_tool(
+        "draft_email",
+        {
+            "service_slug": "software-development",
+            "language": "en",
+            "sender_name": "John Doe",
+            "sender_email": "john@example.com",
+            "custom_text": "I need help with a custom web application."
+        }
+    )
+    print(email)
+    
+    await client.disconnect()
+
+# Run with asyncio
+import asyncio
+asyncio.run(main())
+```
+
+### JavaScript/Node.js Client
+
+```javascript
+const { Client } = require('@modelcontextprotocol/sdk');
+
+async function main() {
+    const client = new Client('jaraco-website', { url: 'http://localhost:8081' });
+    await client.connect();
+    
+    // List resources
+    const resources = await client.listResources();
+    console.log(`Found ${resources.length} resources`);
+    
+    // Read a resource
+    const post = await client.readResource('blog_posts/from-data-chaos-to-efficient-automation');
+    console.log(post);
+    
+    // Draft an email
+    const email = await client.callTool('draft_email', {
+        service_slug: 'software-development',
+        language: 'en',
+        sender_name: 'John Doe',
+        sender_email: 'john@example.com',
+        custom_text: 'I need help with a custom web application.'
+    });
+    console.log(email);
+    
+    await client.disconnect();
+}
+
+main().catch(console.error);
+```
+
+## API Reference
+
+The MCP server uses the **Streamable HTTP transport** with the following endpoint:
+- **Base URL**: `http://localhost:8081/mcp`
+- **Transport**: Streamable HTTP (MCP v2 recommended)
+
+### MCP Protocol
+
+This server implements the MCP (Model Context Protocol) v2 specification. Clients should use an MCP client library for their language.
+
+### list_resources
+
+List all available resources or filter by type.
+
+**MCP Request**:
+```json
+{
+  "method": "list_resources",
+  "params": {
+    "uri": "blog_posts/"
+  }
+}
+```
+
+**MCP Response**:
+```json
+{
+  "resources": [
+    {
+      "uri": "blog_posts/from-data-chaos-to-efficient-automation",
+      "name": "From Data Chaos to Efficient Automation",
+      "description": "How to transform...",
+      "mimeType": "text/markdown"
+    }
+  ]
+}
+```
+
+### read_resource
+
+Read a specific resource by URI.
+
+**MCP Request**:
+```json
+{
+  "method": "read_resource",
+  "params": {
+    "uri": "blog_posts/from-data-chaos-to-efficient-automation"
+  }
+}
+```
+
+**MCP Response**:
+```json
+{
+  "contents": [
+    {
+      "type": "text",
+      "text": "# From Data Chaos to Efficient Automation\n\n...",
+      "mimeType": "text/markdown"
+    }
+  ]
+}
+```
+
+### call_tool (draft_email)
+
+Draft an email for a service.
+
+**MCP Request**:
+```json
+{
+  "method": "call_tool",
+  "params": {
+    "name": "draft_email",
+    "arguments": {
+      "service_slug": "software-development",
+      "language": "en",
+      "sender_name": "John Doe",
+      "sender_email": "john@example.com",
+      "custom_text": "I need help with..."
+    }
+  }
+}
+```
+
+**MCP Response**:
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"subject\": \"Inquiry: Software Development Services\", \"body\": \"Dear Jaraco Team...\", ...}",
+      "mimeType": "application/json"
+    }
+  ],
+  "isError": false
+}
+```
+
+### Using MCP CLI
+
+If you have the MCP CLI installed, you can test the server directly:
+
+```bash
+# Install MCP CLI
+pip install "mcp[cli]>=2.2.0,<3"
+
+# Run the server in dev mode
+mcp dev mcp_server.server
+
+# Or run and connect
+mcp run mcp_server.server
+```
+
+The MCP CLI will automatically use the correct protocol and transport settings.
+
+## Available Services
+
+The following services are available through the MCP server:
+
+| Service Slug | Description |
+|--------------|-------------|
+| `software-development` | Custom software development services |
+| `consulting` | IT consulting and advisory services |
+| `it-architecture` | IT architecture design and review |
+| `linux-consulting` | Linux system consulting |
+| `code-review` | Code review and quality assessment |
+| `technology-assessment` | Technology stack evaluation |
+
+## Available Categories
+
+Content is organized into the following categories:
+
+| Category Slug | Description |
+|---------------|-------------|
+| `software-engineering` | Software development and engineering |
+| `consulting` | Consulting services |
+| `linux` | Linux and infrastructure services |
+| `automation` | Automation and workflow improvement |
+
+## Project Structure
+
+```
+mcp_server/
+├── __init__.py           # Package initialization
+├── server.py             # Main MCP server implementation
+├── content_loader.py     # Content loading and caching
+├── email_templates.py    # Email template definitions
+├── config.py             # Server configuration
+├── requirements.txt       # Python dependencies
+├── Dockerfile            # Docker configuration
+└── README.md             # This file
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Install test dependencies
+pip install pytest pytest-asyncio
+
+# Run tests
+pytest tests/test_mcp_server.py -v
+```
+
+### Code Style
+
+This project follows PEP 8 style guidelines. Use `black` and `isort` for formatting:
+
+```bash
+pip install black isort
+black mcp_server/
+isort mcp_server/
+```
+
+## Security
+
+- The MCP server provides **read-only access** to content
+- No authentication is required by default (can be added if needed)
+- All inputs are validated before processing
+- Rate limiting is configured to prevent abuse
+- The server runs as a non-root user in Docker
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Content not found**: Ensure `CONTENT_ROOT` points to the correct directory
+2. **Connection refused**: Check that the server is running and the port is correct
+3. **Rate limiting**: Reduce request frequency if you hit rate limits
+
+### Debug Mode
+
+Enable debug logging for troubleshooting:
+
+```bash
+LOG_LEVEL=DEBUG python -m mcp_server.server
+```
+
+## License
+
+This MCP server is part of the Jaraco website and is licensed under the same terms as the main project.
+
+## Support
+
+For questions or issues:
+
+- **Email**: info@jaraco.de
+- **Website**: https://jaraco-gmbh.de
+- **GitHub**: https://github.com/jaracogmbh/jaraco-website
+
+## Version History
+
+- **1.0.0**: Initial release with blog posts, services, categories, and email drafting