Alayman MCP Server

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 - 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

npm install

Building

npm run build

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:

git clone <repository-url>
cd alayman-mcp-ts
npm install
npm run build

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.

{
  "mcpServers": {
    "alayman": {
      "command": "node",
      "args": [
        "/absolute/path/to/alayman-mcp-ts/build/index.js"
      ]
    }
  }
}

Example for macOS/Linux:

{
  "mcpServers": {
    "alayman": {
      "command": "node",
      "args": [
        "/Users/yourname/Projects/alayman-mcp-ts/build/index.js"
      ]
    }
  }
}

Example for Windows:

{
  "mcpServers": {
    "alayman": {
      "command": "node",
      "args": [
        "C:\\Users\\yourname\\Projects\\alayman-mcp-ts\\build\\index.js"
      ]
    }
  }
}

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:

List all articles from alayman.io

Search for specific topics:

Find all Angular articles from alayman

Limit results:

Show me the 10 most recent articles

Pagination:

Get articles 20-40 from alayman

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:

{
  "articles": [
    {
      "id": 307,
      "title": "Article Title",
      "subtitle": "Article subtitle...",
      "image": "https://...",
      "url": "https://medium.com/...",
      "name": "Author Name",
      "time": "2025-08-23T06:07:28Z",
      "readtime": "5 min read",
      "category": 1,
      "description": "",
      "shareCount": 0,
      "checkCount": 3
    }
  ],
  "total": 30,
  "offset": 0,
  "limit": 20,
  "has_more": true
}

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

alayman-mcp-ts/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript (generated)
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore rules
└── README.md