Alayman Article Retrieval

# Alayman MCP Server - Article Retrieval and Search A Model Context Protocol (MCP) server that provides tools and prompts to retrieve and search blog articles from the **Alayman blog** ([A Layman on Medium](https://medium.com/a-layman)) by Jen-Hsuan Hsieh (Sean). ## Overview This MCP server provides tools and prompts to interact with Alayman blog articles, allowing you to: - Fetch paginated article lists (currently 285+ articles available) - Search and filter articles by topic, title, or content - Generate contextual prompts for article discovery - Access article metadata including author, publication time, read time, and engagement metrics ## Features - **Article Retrieval Tool**: Fetches paginated articles with customizable limit and offset - **Article List Prompt**: Generates intelligent prompts for article discovery with optional filters - **Structured Output**: Returns validated data using Pydantic models - **Pagination Support**: Efficient handling of large article collections - **Async HTTP**: Uses httpx for efficient async API calls - **Error Handling**: Comprehensive exception handling for network and HTTP errors - **SSE Transport**: Server-Sent Events support for HTTP-based MCP connections - **Dual Transport**: Supports both stdio (for Claude Desktop/Code) and SSE (for HTTP clients) ## Topics Covered in the Blog The Alayman blog covers a wide range of software engineering topics, including: - **Frontend Development**: React, Angular, Next.js, Vue.js, TypeScript, JavaScript - **Backend Development**: Django, Node.js, NestJS, Python, GraphQL, RESTful APIs - **Data Visualization**: D3.js, Cytoscape.js, Highcharts, ECharts - **Cloud & DevOps**: AWS, Docker, Kubernetes, CI/CD, GitLab, GitHub Actions - **Architecture & Patterns**: Micro Frontends, Design Patterns, System Design - **Testing**: Unit Testing, Integration Testing, Karma, Jasmine - **AI & Tools**: Claude CLI, GitHub Copilot, RAG, LangChain.js - **Web Performance**: SEO, Optimization, Caching, SSR/SSG - **Career & Soft Skills**: Team Management, Digital Nomad Life, Conference Insights ## Requirements - Python 3.11 or higher - uv (package manager) ## Installation 1. Clone this repository 2. Install dependencies: ```bash uv sync ``` 3. Create a `.env` file in the project root with the required configuration: ```bash # Required: API endpoint URL ALAYMAN_API_URL=your_api_url_here # Optional: Port for SSE server (default: 8000) # PORT=8000 ``` ## Usage ### Running the Server The server supports two transport modes: **stdio** and **SSE** (Server-Sent Events). #### SSE Transport (Default) Start the MCP server with SSE transport over HTTP: ```bash uv run server.py ``` By default, the server will start on `http://127.0.0.1:8000` with the SSE endpoint available at: - SSE endpoint: `http://127.0.0.1:8000/sse` - Messages endpoint: `http://127.0.0.1:8000/messages` You can specify a custom port using the `PORT` environment variable: ```bash PORT=3000 uv run server.py ``` #### Stdio Transport For stdio transport (used by Claude Desktop and some MCP clients), the server will automatically use stdio when invoked by those clients through their configuration files. ### Testing with MCP Inspector The MCP Inspector is a web-based tool for testing MCP servers. #### Testing with SSE Transport To test the SSE server with MCP Inspector: 1. Start the server in SSE mode: ```bash uv run server.py ``` 2. In a separate terminal, start the MCP Inspector and connect to the SSE endpoint: ```bash npx @modelcontextprotocol/inspector http://127.0.0.1:8000/sse ``` The inspector will connect to your running SSE server and allow you to test tools and prompts interactively. #### Testing with Stdio Transport For stdio transport testing: ```bash npx @modelcontextprotocol/inspector uv run server.py ``` This will start the inspector and connect it to your server automatically using stdio. ### Integration with Claude Desktop To use this server with Claude Desktop, add it to your Claude Desktop configuration: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json` ```json { "mcpServers": { "shellserver": { "command": "uv", "args": ["run", "/absolute/path/to/server.py"], "cwd": "/absolute/path/to/shellserver" } } } ``` Restart Claude Desktop after updating the configuration. ### Integration with Claude Code Claude Code supports both stdio and SSE transport for MCP servers. Choose the method that best fits your needs. #### Option 1: SSE Transport (Recommended for Remote/Network Access) First, start the MCP server with SSE transport: ```bash uv run server.py ``` Then add the SSE server to Claude Code using the `claude mcp add` command: ```bash claude mcp add --scope user --transport sse alayman http://127.0.0.1:8000/sse ``` This will add the SSE server with the name "alayman" to your user-level MCP configuration. Alternatively, you can manually add it to your Claude Code MCP configuration: - **macOS/Linux**: `~/.claude/mcp.json` - **Windows**: `%USERPROFILE%\.claude\mcp.json` ```json { "mcpServers": { "alayman": { "url": "http://127.0.0.1:8000/sse" } } } ``` **For remote SSE servers:** ```json { "mcpServers": { "alayman": { "url": "https://your-server.com/mcp/alayman/sse" } } } ``` #### Option 2: Stdio Transport (Default) Add the server to Claude Code using the `claude mcp add` command. From the project directory, run: ```bash claude mcp add --scope user alayman uv run $(pwd)/server.py ``` This will add the server with the name "alayman" to your user-level MCP configuration, making it available across all your Claude Code sessions. Alternatively, you can manually add it to your Claude Code MCP configuration: ```json { "mcpServers": { "alayman": { "command": "uv", "args": ["run", "/absolute/path/to/server.py"], "cwd": "/absolute/path/to/alayman-mcp" } } } ``` #### Reloading Configuration After updating the configuration, restart Claude Code or reload the MCP servers for the changes to take effect. ### Integration with Docker and Claude Code #### Build the Docker image ```bash docker build -t alayman . ``` #### Option 1: Docker with SSE Transport Run the Docker container with SSE transport: ```bash docker run -d -p 8000:8000 \ -e ALAYMAN_API_URL=your_api_url \ --name alayman-mcp \ alayman ``` Then add the SSE endpoint to Claude Code: ```bash claude mcp add --scope user --transport sse alayman http://127.0.0.1:8000/sse ``` Or manually configure: ```json { "mcpServers": { "alayman": { "url": "http://127.0.0.1:8000/sse" } } } ``` #### Option 2: Docker with Stdio Transport Add the Docker container as the MCP server with stdio: ```bash claude mcp add-json --scope user alayman '{"type":"stdio","command":"docker","args":["run","-i","--rm","--init","-e","DOCKER_CONTAINER=true","alayman"]}' ``` Or manually configure: ```json { "mcpServers": { "alayman": { "command": "docker", "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "alayman"] } } } ``` ### Using SSE Transport with MCP Clients When running the server with SSE transport, you can connect to it from any MCP client that supports SSE/HTTP connections. #### Connection Details - **Base URL**: `http://127.0.0.1:8000` - **SSE Endpoint**: `http://127.0.0.1:8000/sse` - **Messages Endpoint**: `http://127.0.0.1:8000/messages` - **Transport Type**: `sse` #### Example: Connecting with MCP Client SDK If you're building a custom MCP client using the MCP SDK, you can connect to the SSE server like this: **Python:** ```python from mcp.client import Client from mcp.client.sse import sse_client async with sse_client("http://127.0.0.1:8000/sse") as (read, write): async with Client(read, write) as client: # Use the client to call tools result = await client.call_tool("get_articles", {"limit": 10}) print(result) ``` **TypeScript/JavaScript:** ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"; const transport = new SSEClientTransport( new URL("http://127.0.0.1:8000/sse") ); const client = new Client({ name: "example-client", version: "1.0.0", }, { capabilities: {} }); await client.connect(transport); // Call tools const result = await client.callTool({ name: "get_articles", arguments: { limit: 10 } }); ``` #### Benefits of SSE Transport - **HTTP-based**: Works through standard HTTP infrastructure - **Firewall-friendly**: Easier to deploy in corporate environments - **Debugging**: Can use standard HTTP tools (curl, Postman, etc.) - **Scalability**: Can be load-balanced and proxied - **No stdio**: Doesn't require process spawning #### Deploying SSE Server For production deployments, you can run the SSE server as a service: **Using systemd (Linux):** ```ini [Unit] Description=Alayman MCP Server After=network.target [Service] Type=simple User=www-data WorkingDirectory=/path/to/alayman-mcp Environment="ALAYMAN_API_URL=your_api_url" Environment="PORT=8000" ExecStart=/usr/local/bin/uv run server.py Restart=always [Install] WantedBy=multi-user.target ``` **Using Docker for SSE:** ```bash # Run with SSE transport exposed on port 8000 docker run -d \ -p 8000:8000 \ -e ALAYMAN_API_URL=your_api_url \ -e PORT=8000 \ --name alayman-mcp \ alayman ``` **Behind a reverse proxy (nginx):** ```nginx location /mcp/alayman/ { proxy_pass http://127.0.0.1:8000/; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_set_header Host $host; proxy_buffering off; proxy_cache off; } ``` ## Quick Start Examples Once integrated with Claude Desktop or Claude Code, you can use the server in various ways: **Direct tool usage:** ``` Show me the first 10 articles from the Alayman blog Get articles 20-30 from the blog Retrieve 5 articles starting from position 10 ``` **Using the prompt command (Claude Code):** ```bash /alayman:list_articles 10 "the title contains 'React'" /alayman:list_articles 5 "articles about Django" /alayman:list_articles 15 "published in the last year" ``` **Natural language queries:** ``` Find all articles about Angular Show me articles related to AWS List articles about data visualization with D3.js ``` ## Available Tools and Prompts ### Tool: get_articles Retrieves a paginated list of blog articles from the API. **Parameters**: - `limit` (int, optional): Number of articles to return (default: 20, min: 1, max: 100) - `offset` (int, optional): Number of articles to skip (default: 0, min: 0) **Returns**: An ArticlesResponse object containing: - `articles` (list[Article]): List of article objects - `total` (int): Total number of articles available - `offset` (int): Current offset value - `limit` (int): Current limit value - `has_more` (bool): Whether more articles are available **Article Object Fields**: - `id` (int): Unique article identifier - `title` (str): Article title - `subtitle` (str): Article subtitle - `image` (str): URL to article image - `url` (str): URL to article page - `author` (str): Article author name - `time` (str): Publication timestamp (ISO 8601) - `readtime` (str): Estimated reading time - `category` (int): Article category ID - `description` (str): Article description - `shareCount` (int): Number of shares - `checkCount` (int): Number of views/checks **Example usage in Claude**: ``` Can you retrieve the first 10 articles? Can you get articles 20-40? Fetch the latest 5 articles from the blog. ``` ### Prompt: list_articles Generates an intelligent prompt to list and filter Alayman's articles. This prompt will instruct the LLM to use the get_articles tool and apply specific filters. **Parameters**: - `number` (int, optional): Number of articles to list (default: 10) - `condition` (str, optional): Condition or filter criteria for articles (default: "") **Example usage in Claude Code**: ``` /alayman:list_articles 5 "the title contains 'React'" /alayman:list_articles 10 "published in 2024" /alayman:list_articles 15 "related to Python" ``` When you run this prompt, it generates instructions for Claude to fetch articles and apply your specified conditions when presenting the results. ## Project Structure ``` alayman-mcp/ ├── server.py # Main MCP server implementation ├── pyproject.toml # Project dependencies and metadata ├── uv.lock # Dependency lock file ├── README.md # This file ├── CLAUDE.md # Claude Code project instructions ├── reference.md # Additional reference documentation ├── Dockerfile # Docker container configuration ├── .dockerignore # Docker build exclusions ├── .env.example # Example environment variables ├── .env # Environment variables (not in git) ├── .python-version # Python version specification (3.11) ├── .gitignore # Git exclusions ├── .venv/ # Virtual environment (created by uv) └── rules/ # Development rules and guidelines └── python.md # Python coding standards ``` ## Dependencies - `mcp[cli]>=1.22.0` - Model Context Protocol SDK with CLI support - `httpx>=0.28.0` - Modern async HTTP client - `python-dotenv` - Environment variable management from .env files ## Development ### Architecture The server uses the FastMCP framework from the MCP Python SDK, which provides: - Simple decorator-based tool and prompt registration - Automatic JSON schema generation from type hints - Built-in validation using Pydantic models - Support for async operations ### Code Structure 1. **Pydantic Models**: - `Article`: Defines the article schema for type-safe data validation - `ArticlesResponse`: Defines the paginated response structure 2. **Tool Function**: The `get_articles()` async function fetches and validates article data with pagination support 3. **Prompt Function**: The `list_articles()` function generates contextual prompts for article discovery 4. **Server Instance**: FastMCP server configured with stdio transport ## Error Handling The server includes comprehensive error handling for: - HTTP errors (4xx, 5xx responses) - Network connectivity issues - JSON parsing errors - Data validation failures All errors are caught and returned as descriptive exception messages. ## License This project is provided as-is for educational and development purposes. ## Resources - [MCP Documentation](https://modelcontextprotocol.io/) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [FastMCP Guide](https://github.com/modelcontextprotocol/python-sdk/tree/main/src/mcp/server/fastmcp)