Alayman MCP

Alayman MCP服务器-文章检索和搜索

一个模型上下文协议（MCP）服务器，提供工具和提示，用于从 阿拉曼博客 (A Layman on Medium)谢仁勋（Sean）。

概述

此MCP服务器提供与Alayman博客文章交互的工具和提示，允许您：

• 获取分页文章列表（目前有285+篇文章可用）
• 按主题、标题或内容搜索和筛选文章
• 为文章发现生成上下文提示
• 访问文章元数据，包括作者、发表时间、阅读时间和参与度指标

特性

• 文章检索工具：获取具有可自定义限制和偏移的分页文章
• 文章列表提示：使用可选筛选器生成文章发现的智能提示
• 结构化输出：使用Pydantic模型返回经过验证的数据
• 分页支持：高效处理大量文章收藏
• 异步HTTP：使用httpx进行高效的异步API调用
• 错误处理：针对网络和HTTP错误的全面异常处理
• 苏格兰和南方能源公司运输：基于HTTP的MCP连接的服务器发送事件支持
• 双重运输：支持stdio（用于克劳德桌面/代码）和SSE（用于HTTP客户端）

博客涵盖的主题

Alayman博客涵盖了广泛的软件工程主题，包括：

• 前端开发：React、Angular、Next.js、Vue.js、TypeScript、JavaScript
• 后端开发：Django、Node.js、NestJS、Python、GraphQL、RESTful API
• 数据可视化：D3.js、Cytoscape.js、Highcharts、ECharts
• 云和DevOps：AWS、Docker、Kubernetes、CI/CD、GitLab、GitHub Actions
• 架构与模式：微前端、设计模式、系统设计
• 测试：单元测试、集成测试、Karma、Jasmine
• 人工智能和工具：Claude CLI、GitHub Copilot、RAG、LangChain.js
• 网络性能：SEO、优化、缓存、SSR/SSG
• 职业与软技能：团队管理、数字游牧生活、会议洞察

需求

• Python 3.11或更高版本
• uv（包管理器）

安装

1. 克隆此存储库
2. 安装依赖项：

uv sync

1. 创建一个 .env 项目根目录中具有所需配置的文件：

# Required: API endpoint URL
ALAYMAN_API_URL=your_api_url_here

# Optional: Port for SSE server (default: 8000)
# PORT=8000

用法

运行服务器

服务器支持两种传输模式： 标准 和 上海证券交易所 （服务器发送的事件）。

苏格兰和南方能源公司运输（默认）

使用HTTP上的SSE传输启动MCP服务器：

uv run server.py

默认情况下，服务器将启动 http://127.0.0.1:8000 SSE端点位于：

• SSE端点： http://127.0.0.1:8000/sse
• 消息端点： http://127.0.0.1:8000/messages

您可以使用指定自定义端口 PORT 环境变量：

PORT=3000 uv run server.py

标准运输

对于stdio传输（由Claude Desktop和一些MCP客户端使用），当这些客户端通过其配置文件调用时，服务器将自动使用stdio。

MCP检验员测试

MCP Inspector是一个基于网络的工具，用于测试MCP服务器。

使用SSE Transport进行测试

要使用MCP检查器测试SSE服务器，请执行以下操作：

1. 以SSE模式启动服务器：

uv run server.py

1. 在单独的终端中，启动MCP检查器并连接到SSE端点：

npx @modelcontextprotocol/inspector http://127.0.0.1:8000/sse

检查器将连接到正在运行的SSE服务器，并允许您以交互方式测试工具和提示。

使用Stdio Transport进行测试

对于stdio传输测试：

npx @modelcontextprotocol/inspector uv run server.py

这将启动检查器，并使用stdio自动将其连接到您的服务器。

与Claude Desktop集成

要将此服务器与Claude Desktop一起使用，请将其添加到您的Claude Desktop配置中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shellserver": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/server.py"],
      "cwd": "/absolute/path/to/shellserver"
    }
  }
}

更新配置后重新启动Claude Desktop。

与Claude Code集成

Claude Code支持MCP服务器的stdio和SSE传输。选择最适合您需求的方法。

选项1:SSE传输（建议用于远程/网络访问）

首先，使用SSE传输启动MCP服务器：

uv run server.py

然后使用以下命令将SSE服务器添加到Claude代码中 claude mcp add 命令：

claude mcp add --scope user --transport sse alayman http://127.0.0.1:8000/sse

这将把名为“alayman”的SSE服务器添加到您的用户级MCP配置中。

或者，您可以手动将其添加到Claude Code MCP配置中：

• macOS/Linux: ~/.claude/mcp.json
• 视窗: %USERPROFILE%\.claude\mcp.json

{
  "mcpServers": {
    "alayman": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

对于远程SSE服务器：

{
  "mcpServers": {
    "alayman": {
      "url": "https://your-server.com/mcp/alayman/sse"
    }
  }
}

选项2：标准传输（默认）

使用以下命令将服务器添加到Claude代码中 claude mcp add 命令。从项目目录中，运行：

claude mcp add --scope user alayman uv run $(pwd)/server.py

这将把名为“alayman”的服务器添加到您的用户级MCP配置中，使其在所有Claude Code会话中都可用。

或者，您可以手动将其添加到Claude Code MCP配置中：

{
  "mcpServers": {
    "alayman": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/server.py"],
      "cwd": "/absolute/path/to/alayman-mcp"
    }
  }
}

重新加载配置

更新配置后，重新启动Claude Code或重新加载MCP服务器以使更改生效。

与Docker和Claude代码集成

构建Docker镜像

docker build -t alayman .

选项1：使用SSE传输的Docker

使用SSE传输运行Docker容器：

docker run -d -p 8000:8000 \
  -e ALAYMAN_API_URL=your_api_url \
  --name alayman-mcp \
  alayman

然后将SSE端点添加到Claude代码中：

claude mcp add --scope user --transport sse alayman http://127.0.0.1:8000/sse

或手动配置：

{
  "mcpServers": {
    "alayman": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

选项2：带Stdio传输的Docker

使用stdio将Docker容器添加为MCP服务器：

claude mcp add-json --scope user alayman '{"type":"stdio","command":"docker","args":["run","-i","--rm","--init","-e","DOCKER_CONTAINER=true","alayman"]}'

或手动配置：

{
  "mcpServers": {
    "alayman": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "alayman"]
    }
  }
}

在MCP客户端上使用SSE传输

当使用SSE传输运行服务器时，您可以从任何支持SSE/HTTP连接的MCP客户端连接到它。

连接详细信息

• 基本URL: http://127.0.0.1:8000
• SSE端点: http://127.0.0.1:8000/sse
• 消息端点: http://127.0.0.1:8000/messages
• 运输类型: sse

示例：连接MCP客户端SDK

如果您正在使用MCP SDK构建自定义MCP客户端，则可以按如下方式连接到SSE服务器：

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)

Types/JavaScript：

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 }
});

苏格兰和南方能源公司运输的好处

• 基于HTTP：通过标准HTTP基础架构工作
• 防火墙友好：更易于在企业环境中部署
• 调试：可以使用标准HTTP工具（curl、Postman等）
• 可扩展性：可以进行负载平衡和代理
• 无工作室：不需要进程生成

部署SSE服务器

对于生产部署，您可以将SSE服务器作为服务运行：

使用systemd（Linux）：

[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

使用Docker进行SSE：

# 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

反向代理（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;
}

快速入门示例

一旦与Claude Desktop或Claude Code集成，您就可以以各种方式使用服务器：

直接工具使用：

Show me the first 10 articles from the Alayman blog
Get articles 20-30 from the blog
Retrieve 5 articles starting from position 10

使用提示命令（Claude Code）：

/alayman:list_articles 10 "the title contains 'React'"
/alayman:list_articles 5 "articles about Django"
/alayman:list_articles 15 "published in the last year"

自然语言查询：

Find all articles about Angular
Show me articles related to AWS
List articles about data visualization with D3.js

可用工具和提示

工具：获取文章

从API检索博客文章的分页列表。

参数:

• limit （int，可选）：要返回的文章数（默认值：20，最小值：1，最大值：100）
• offset （int，可选）：要跳过的文章数（默认值：0，最小值：0）

退货：ArticlesResponse对象包含：

• articles （列表\[文章\]）：文章对象列表
• total （int）：可用文章总数
• offset （int）：当前偏移值
• limit （int）：电流限制值
• has_more （bool）：是否有更多文章可用

文章对象字段:

• id （int）：唯一物品标识符
• title （str）：文章标题
• subtitle （str）：文章副标题
• image （str）：文章图片的URL
• url （str）：文章页面的URL
• author （str）：文章作者姓名
• time （str）：发布时间戳（ISO 8601）
• readtime （str）：预计阅读时间
• category （int）：文章类别ID
• description （str）：文章描述
• shareCount （int）：股份数量
• checkCount （int）：查看/检查次数

Claude中的示例用法:

Can you retrieve the first 10 articles?
Can you get articles 20-40?
Fetch the latest 5 articles from the blog.

提示：列表_文章

生成一个智能提示，以列出和筛选Alayman的文章。此提示将指示LLM使用get_articles工具并应用特定的过滤器。

参数:

• number （int，可选）：要列出的文章数（默认值：10）
• condition （str，可选）：文章的条件或筛选条件（默认值：“”）

Claude代码中的示例用法:

/alayman:list_articles 5 "the title contains 'React'"
/alayman:list_articles 10 "published in 2024"
/alayman:list_articles 15 "related to Python"

当您运行此提示时，它会为Claude生成指令，以获取文章并在呈现结果时应用您指定的条件。

项目结构

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

依赖项

• mcp[cli]>=1.22.0 -支持CLI的模型上下文协议SDK
• httpx>=0.28.0 -现代异步HTTP客户端
• python-dotenv -从.env文件管理环境变量

发展

建筑

服务器使用MCP Python SDK中的FastMCP框架，该框架提供：

• 基于简单装饰器的工具和快速注册
• 从类型提示自动生成JSON模式
• 使用Pydantic模型进行内置验证
• 支持异步操作

编码结构

1. Pydantic模型:

- Article：定义类型安全数据验证的项目架构 - ArticlesResponse：定义分页响应结构

1. 工具功能：The get_articles() async函数通过分页支持获取和验证文章数据
2. 提示功能：The list_articles() 函数为文章发现生成上下文提示
3. 服务器实例：配置了stdio传输的FastMCP服务器

错误处理

该服务器包括全面的错误处理功能，用于：

• HTTP错误（4xx、5xx响应）
• 网络连接问题
• JSON解析错误
• 数据验证失败

所有错误都会被捕获并作为描述性异常消息返回。

许可证

本项目按原样提供，用于教育和发展目的。

资源

• MCP文件
• MCP Python SDK
• FastMCP指南