# Alayman MCP Server

A Model Context Protocol (MCP) server that provides access to articles from [alayman.io](https://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

```bash
npm install
```

## Building

```bash
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:

```bash
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.

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

**Example for macOS/Linux:**
```json
{
  "mcpServers": {
    "alayman": {
      "command": "node",
      "args": [
        "/Users/yourname/Projects/alayman-mcp-ts/build/index.js"
      ]
    }
  }
}
```

**Example for Windows:**
```json
{
  "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:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Maximum number of articles to return (default: 20) |
| `offset` | number | No | Number of articles to skip for pagination (default: 0) |
| `search` | string | No | Search term to filter articles by title, subtitle, or content |

**Usage Examples:**

1. **Fetch all articles (default):**
   ```json
   {}
   ```

2. **Search for specific topics:**
   ```json
   {
     "search": "Angular"
   }
   ```

3. **Limit results:**
   ```json
   {
     "limit": 10
   }
   ```

4. **Pagination (get articles 20-40):**
   ```json
   {
     "limit": 20,
     "offset": 20
   }
   ```

5. **Combined search with limit:**
   ```json
   {
     "search": "React",
     "limit": 5
   }
   ```

**Response Format:**

```json
{
  "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            # This file
```

## Development

### Watch Mode

```bash
npm run watch
```

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:

| What you want | Example query |
|---------------|---------------|
| All articles | "List all alayman's articles" |
| Search by topic | "Find all Angular articles from alayman" |
| Search by topic | "Show me React articles" |
| Limited results | "Get the latest 10 articles from alayman" |
| Pagination | "Show me articles 20-30" |
| Recent articles | "What are the newest articles on alayman.io?" |

### Direct Tool Usage

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

```typescript
// Through MCP client
const result = await client.callTool("fetch-articles", {
  search: "TypeScript",
  limit: 5
});
```

## Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Claude Code Documentation](https://docs.claude.com/claude-code)
- [Alayman.io](https://alayman.io)