portfolio-mcp-server

Name: portfolio-mcp-server
Author: ayush-s-tomar

本地服务

github.com/ayush-s-tomar其他12 天前更新

代码仓库

关于 portfolio-mcp-server

portfolio-mcp-server 让 MCP 客户端查询 Ayush Singh Tomar 的项目、技术栈和履历摘要。它通过 stdio 在本地提供五种查询工具，数据随服务打包。

主要功能

01列出所有项目
02获取项目详情
03按技术搜索项目
04推荐代表项目
05总结履历背景

适用场景

01查找使用某项技术的项目
02查看特定项目详情
03快速了解作品集内容

MCP 相关

这是一个向 MCP 客户端提供五种作品集查询工具的 MCP 服务，通过 stdio 通信并读取随服务打包的项目数据。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "ayush-s-tomar-portfolio": {
      "command": "uvx",
      "args": [
        "portfolio-mcp-server"
      ]
    }
  }
}

启动命令uvx portfolio-mcp-server

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiportfolio-mcp-server1.0.4stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

🗂️ Portfolio MCP Server

向 AI 询问我的作品，它会根据真实数据作答，而不是根据 PDF。

一个让我的 AI 项目作品集变得可查询的 MCP 服务。
将它连接到 Claude、Cursor 或任何 MCP 客户端，然后直接提问。

快速开始 · 工具 · 演示 · 连接客户端 · 限制 · 路线图

⚡ 快速开始

服务命令（客户端会替你启动它；手动运行时，它只会静静等待客户端连接）：

uvx --with "mcp<2" portfolio-mcp-server

只需一行即可将它添加到 Claude Code：

claude mcp add --scope user portfolio -- uvx --with "mcp<2" portfolio-mcp-server

然后提问：

“Ayush 用 LangGraph 构建过什么？”

更喜欢 pip？pip install portfolio-mcp-server

💡 为什么要做这个

大多数 AI 开发者的作品集只是一串链接。这是一个围绕我自己的作品集构建的可用 MCP 服务，使用 Agentic 产品连接工具时采用的同一协议。它是对规范的真实实现，也直接回应了“向我证明你真的用 MCP 构建过东西”。


📦 已发布	已在 PyPI 和官方 MCP 注册表上线
🔧 5 个工具	列表、详情查询、技术栈搜索、代表作推荐、简历摘要
✅ 已测试	每次推送都会运行代码检查、类型检查和 stdio 冒烟测试

🧰 工具

工具	功能	可以这样问
`list_projects`	列出数据集中的每个项目摘要	“列出 Ayush 构建过的所有项目。”
`get_project_details(project_name)`	获取某个项目的完整详情	“介绍一下他的 RAG 聊天机器人。”
`search_projects_by_stack(technology)`	查找使用指定技术的项目	“哪些项目使用了 FastAPI？”
`get_flagship_project`	推荐最适合优先了解的项目	“我应该先看哪个项目？”
`get_resume_summary`	背景、目标职位、核心技术栈	“总结一下他的背景。”

🧠 工作原理

MCP client (Claude, Cursor, agents)  <--stdio-->  portfolio-mcp-server (FastMCP)  -->  bundled project data

客户端会将服务作为本地进程启动，并通过 stdio 与它通信。服务根据随附的项目数据响应每次工具调用。所有内容都在本地运行，无需托管，也不需要 API 密钥。

🎬 演示

MCP Inspector：工具发现	实时聊天演示

🎥 完整视频演示

https://github.com/user-attachments/assets/4c1b844a-087f-48a6-b156-bdef27282acc

从设置、工具调用到实时回答，全程演示。

## 🔌 连接客户端

Claude Code

claude mcp add --scope user portfolio -- uvx --with "mcp<2" portfolio-mcp-server

Claude Desktop

打开配置文件：

操作系统	路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

如果文件中已有 mcpServers 键，请在其中添加 "portfolio"，而不要覆盖整个文件。

通过 pip 安装：

{
  "mcpServers": {
    "portfolio": {
      "command": "portfolio-mcp-server"
    }
  }
}

从克隆的代码库运行（使用 server.py 的绝对路径）：

{
  "mcpServers": {
    "portfolio": {
      "command": "python",
      "args": ["/absolute/path/to/portfolio-mcp-server/server.py"]
    }
  }
}

重启 Claude Desktop 并询问：“Ayush 用 FastAPI 构建了哪些项目？”

Cursor 和其他客户端

任何能够启动 stdio 服务的 MCP 客户端都可以使用。将 portfolio-mcp-server（执行 pip install 后）或上面的 uvx 命令用作服务命令。

🛠️ 开发

从源代码运行

git clone https://github.com/ayush-s-tomar/portfolio-mcp-server.git
cd portfolio-mcp-server

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -r requirements.txt

使用 MCP Inspector 进行交互式测试：

mcp dev server.py

这会打开一个浏览器界面，你可以在其中调用每个工具并检查原始请求和响应载荷。

测试与 CI

每次推送和拉取请求都会通过 GitHub Actions 运行以下检查：

检查项	命令
Lint	`ruff check .`
类型检查	`mypy server.py`
冒烟测试	启动服务并通过 stdio 调用全部 5 个工具，确认每个工具都返回有效且符合架构的 JSON

创建 PR 前，请在本地运行相同的检查：

pip install -r requirements-dev.txt
ruff check .
mypy server.py
pytest

参见 .github/workflows/ci.yml。

项目结构

portfolio-mcp-server/
|-- portfolio_mcp_server/
|   |-- __init__.py
|   `-- server.py          # packaged module (what PyPI ships)
|-- server.py              # top-level entry point (dev / MCP Inspector / CI)
|-- tests/
|   |-- smoke_test.py      # stdio smoke test: calls all 5 tools, validates JSON schema
|   |-- test_tools.py      # per-tool tests
|   |-- test_data.py       # data integrity checks for the bundled projects
|   `-- check_links.py     # checks every URL in the data (runs weekly in CI)
|-- assets/                # demo GIF and screenshots
|-- .github/
|   |-- workflows/         # ci.yml, links.yml
|   |-- ISSUE_TEMPLATE/
|   |-- PULL_REQUEST_TEMPLATE.md
|   `-- dependabot.yml
|-- pyproject.toml         # PyPI packaging config
|-- server.json            # MCP registry manifest
|-- requirements.txt
|-- requirements-dev.txt
|-- claude_desktop_config_snippet.json
|-- CHANGELOG.md
|-- CONTRIBUTING.md
|-- SECURITY.md
`-- LICENSE

构建技术： Python 3.10+ · MCP Python SDK（FastMCP）· stdio 传输 · 已作为 io.github.ayush-s-tomar/portfolio-mcp-server 注册到 MCP 注册表

⚠️ 已知限制

警告： 已安装的软件包是一个快照。 pip install 安装的是该版本发布时的作品集（撰写本文时为 v1.0.4，于 2026-10-27 发布）。此后添加的项目和更新的演示链接，在发布新版本前都不会显示；工具响应目前也无法说明数据的新旧程度。

静态项目数据。 工具读取打包的数据，因此更新项目需要编辑数据并重新发布。目前尚未与 GitHub 仓库或作品集网站实时同步。
仅支持 stdio。 它适用于能够启动进程的本地客户端，例如 Claude Desktop，但目前没有供远程客户端使用的 HTTP/SSE 选项。
每次搜索一种技术。 search_projects_by_stack 每次调用只会按一种技术筛选，因此目前不支持同时搜索“LangGraph 和 FastAPI”。

🗺️ 路线图

已完成

在 PyPI 发布为可安装的软件包
发布到官方 MCP 服务注册表
刷新打包的项目数据（v1.0.2）
每周通过 CI 检查打包数据中的所有 URL 链接

接下来

启动时从作品集网站获取项目数据，并在离线时回退到打包的快照（使用单一事实来源，避免两份副本逐渐不一致）
每个工具都返回 last_updated 日期，以便回答能说明数据的新旧程度
支持在 search_projects_by_stack 中同时匹配多种技术
除 stdio 外，增加 HTTP/SSE 传输选项，供远程客户端使用

🌐 还收录于

## 📄 许可证

基于 MIT License 发布。

由 Ayush Singh Tomar 构建

GitHub · LinkedIn · 作品集

如果这帮助你构建了自己的 MCP 服务，欢迎在仓库点亮 ⭐。

mcp-name: io.github.ayush-s-tomar/portfolio-mcp-server

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。