Alayman

You can run an MCP server that fetches and searches Alayman blog articles, then use intelligent prompts to discover topics, titles, and content efficiently. This server exposes two transport modes (SSE over HTTP and stdio for local clients) and returns structured article data to help you build tailored article discovery workflows.

How to use

You connect with the server using an MCP client that supports SSE or stdio transports. Start by running the server in SSE mode to enable HTTP connections, or use stdio if your client communicates over standard input/output. Once running, you can retrieve paginated article lists, search by topic or keywords, and generate contextual prompts to refine your discovery. Use the get_articles tool to fetch data and the list_articles prompt to generate targeted queries, then inspect fields like title, subtitle, author, time, readtime, and engagement metrics to decide what to read next.

Key actions you can perform once the server is up include: fetching the first page of articles, pulling a specific range (for example articles 20–40), or requesting a small batch starting from a given offset. Use natural language prompts or your MCP client’s tooling to invoke the corresponding tools and prompts. The output includes article metadata suitable for building dashboards, recommendations, or automated reading lists.

How to install

Prerequisites you need installed on your system: Python 3.11 or higher and the uv package manager.

1. Clone the MCP server project.

2. Install dependencies using the package manager.

3. Create a configuration file that provides the API URL for the Alayman data source.

4. Start the server in SSE mode or stdio mode as needed.

SSE transport configuration and usage

The server exposes an SSE endpoint over HTTP for clients that support HTTP connections. Start the server with the SSE transport and listen on the default port or a port you specify.

You will connect to the SSE endpoint to perform tool invocations and receive streaming results from the MCP client.

Example endpoints when running locally (adjust ports if needed): SSE endpoint at http://127.0.0.1:8000/sse and messages endpoint at http://127.0.0.1:8000/messages.

Stdio transport usage

If your client uses stdio for communication, the server can operate in that mode as well. Start the server so that the standard input/output channel is used for MCP messages.

Configuration and environment

Configure the server with the required API URL and, optionally, a port for the SSE endpoint.

Troubleshooting and notes

Ensure the API URL is reachable and that the server process has the necessary network access. If you encounter HTTP errors or JSON parsing failures, verify that the API endpoint responds with valid data and that your environment variables are correctly set.

Additional guidelines

When you see a task about listing articles, prefer using the list_articles prompt to generate a well-scoped query for Claude Code or your MCP client. The tool get_articles handles pagination and returns article fields such as id, title, subtitle, image, url, author, time, readtime, category, description, shareCount, and checkCount.

Examples of typical usage

{
  "mcpServers": {
    "alayman": {
      "type": "http",
      "name": "alayman_http",
      "url": "http://127.0.0.1:8000/sse",
      "args": []
    }
  },
  "envVars": [
    {"name": "ALAYMAN_API_URL", "description": "API endpoint for Alayman articles", "required": true, "example": "https://api.alayman.blog"},
    {"name": "PORT", "description": "Port for SSE server", "required": false, "example": "8000"}
  ]
}

Sample commands to start and test

Start the server in SSE mode using the standard command and then test the endpoints with your MCP client or curl.

Security considerations

Limit access to the SSE endpoint in production using firewalls or reverse proxies and ensure your API URL is kept secret in client configurations.

Available tools

get_articles

Retrieves a paginated list of blog articles from the API, returning article data and pagination details including total, offset, limit, and has_more.

list_articles

Generates contextual prompts to discover and filter Alayman articles by criteria such as title, topic, or date, guiding the client to apply filters when presenting results.