Alayman MCP Server

A Model Context Protocol (MCP) server that provides access to articles from alayman.io via STDIO transport for use with Claude Code and other MCP clients.

Features

• Tool: - Fetch articles from the alayman.io API with optional filtering

• STDIO Transport - Compatible with Claude Code and other STDIO-based MCP clients

• Type-safe - Built with TypeScript and Zod validation

Installation

Building

Adding to Claude Code

Follow these steps to add the Alayman MCP server to Claude Code:

Step 1: Build the Project

First, clone the repository and build the project:

Step 2: Locate Your Claude Code Configuration File

The configuration file location depends on your operating system:

• macOS/Linux: ~/.config/claude/config.json

• Windows: %APPDATA%\claude\config.json

If the file doesn't exist, create it with an empty JSON object: {}

Step 3: Add the MCP Server Configuration

Edit the configuration file and add the mcpServers section. Important: Use the absolute path to your project's build directory.

Example for macOS/Linux:

Example for Windows:

Step 4: Restart Claude Code

Completely restart Claude Code (quit and reopen) for the changes to take effect.

Step 5: Verify Installation

You can verify the MCP server is working by asking Claude:

• "List all alayman's articles"

• "Fetch articles about React"

• "Show me the latest 5 articles from alayman"

Usage

Once the MCP server is configured, you can interact with it naturally through Claude Code. The server provides the fetch-articles tool that Claude can use automatically based on your requests.

Example Queries

Get all articles:

Search for specific topics:

Limit results:

Pagination:

How It Works

When you make a request related to alayman.io articles, Claude Code will automatically:

1. Recognize that it should use the fetch-articles tool

2. Call the MCP server with appropriate parameters

3. Format and present the results to you

You don't need to manually invoke the tool - just ask naturally!

Available Tools

fetch-articles

Fetches articles from the alayman.io API with optional filtering and pagination.

Parameters:

Usage Examples:

1. Fetch all articles (default):

   {}

2. Search for specific topics:

   { "search": "Angular" }

3. Limit results:

   { "limit": 10 }

4. Pagination (get articles 20-40):

   { "limit": 20, "offset": 20 }

5. Combined search with limit:

   { "search": "React", "limit": 5 }

Response Format:

Response Fields:

• articles: Array of article objects

• total: Total number of articles matching the query

• offset: Current pagination offset

• limit: Maximum articles returned

• has_more: Boolean indicating if more articles are available

Project Structure

Development

Watch Mode

This will recompile TypeScript files automatically when they change.

Logging

All server logs are written to stderr (not stdout) to avoid corrupting MCP protocol messages. Look for logs prefixed with [MCP].

API Documentation

The server fetches data from: https://alayman.io/api/articles

Query parameters supported:

• limit - Maximum results

• offset - Pagination offset

• search - Search filter

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Troubleshooting

Server not appearing in Claude Code

• Verify the path in your config.json is absolute, not relative

• Make sure you ran npm run build after making changes

• Restart Claude Code completely after configuration changes

• Check Claude Code logs for MCP server errors

API errors

• Verify that https://alayman.io/api/articles is accessible

• Check your internet connection

• Review server logs in stderr for detailed error messages

Quick Reference

Common Natural Language Queries

Once installed, you can use these natural language queries with Claude Code:

Direct Tool Usage

If you're building integrations or testing, you can also invoke the tool directly:

Resources

• Model Context Protocol Documentation

• MCP TypeScript SDK

• Claude Code Documentation

• Alayman.io