Gary MCP服务器
用于管理个人工作空间的自定义模型上下文协议(MCP)服务器。节省Cursor IDE使用的AI Agent Token,提供项目文档自动参考、AWS/Fly.io基础设施访问、标记PDF转换和代码分析功能。
主要功能
- 自动引用项目文档:自动扫描和参考工作空间中的文档,以提供开发语言和框架信息。
- 访问AWS基础设施:通过AWS CLI使用jongmun配置文件查看和管理AWS资源。
- 管理Fly.io应用程序:查看Fly.io上发布的应用程序的状态、日志和信息。
- 转换标注PDF:将项目的标记文档转换为PDF。
- 代码分析:分析项目的代码流,查找相关代码,确定可重复使用的函数/变量。
- MCP服务器集成:通过自动集成Cursor使用的其他MCP服务器,您可以在单个服务器上使用所有工具。
- 顺序思维:思维工具 - chrome开发工具:调试Chrome - 超级浏览器mcp:Web抓取、滚动、AI浏览器代理
体系结构
这个项目 独立于功能的MCP服务器由组成。每台服务器都作为Docker容器运行,您可以选择仅使用所需功能。
可用的独立服务器
- aws mcp:运行AWS CLI并查看资源
- flyio mcp:管理Fly.io应用程序
- github mcp:运行GitHub CLI并管理存储库
- db-mcp:访问数据库并运行查询
- pdf mcp:标注→PDF转换
- 官方文件mcp:镜像和检索官方文档
- 超级浏览器mcp:Web抓取、滚动、结构化数据提取和浏览器自动化代理
要求
- Python 3.12或更高版本
- 码头工人
- AWS CLI(需要设置jongmun配置文件)
- Fly.io CLI(可选)
安装和运行
方法1:使用Docker Compose运行所有服务器(推荐)
# 모든 MCP 서버를 한 번에 실행
docker-compose -f docker-compose.mcp.yml up -d
# 특정 서버만 실행
docker-compose -f docker-compose.mcp.yml up -d aws-mcp db-mcp
# 서버 중지
docker-compose -f docker-compose.mcp.yml down方法2:构建和运行单个Docker映像
可以独立构建和运行每台服务器:
# AWS 서버 빌드 및 실행
docker build -f docker/aws-cli-mcp.Dockerfile -t aws-mcp .
docker run -it --rm \
-v ~/.aws:/root/.aws:ro \
-v ~/.zshrc:/root/.zshrc:ro \
-e AWS_PROFILE=jongmun \
-e SHELL_RC_PATH=/root/.zshrc \
aws-mcp卷/环境说明:
/Users/gary/Documents/workspace:/workspace:ro:以只读方式装载工作空间目录
~/.aws:/root/.aws:ro:以只读方式挂载AWS配置文件
~/.zshrc:/root/.zshrc:ro:向容器提供主机zshrc(自动加载AWS/Fly.io令牌)
WORKSPACE_PATH:要在容器中引用的工作空间路径
SHELL_RC_PATH:CLI服务引用的shell rc文件路径(默认)/root/.zshrc)
- 配置环境变量
- WORKSPACE_PATH:MCP服务器浏览文档的默认路径。构建Docker时 --build-arg,运行时 -e可以用覆盖。 - SHELL_RC_PATH:AWS/Fly.io CLI引用的shell rc文件路径。主机的 .zshrc安装后,如果指定路径,CLI服务将 export AWS_*, export FLY_* 自动加载值。 - AWS_PROFILE, FLY_*:必要时添加 -e 作为标志注入或 .zshrc呃 export 请后挂载。
3.本地开发环境(无Docker)
# uv 설치
pip install uv
# 의존성 설치
uv pip install -e .
# 서버 실행
python -m src.serverCursor IDE集成
设置文件位置
Cursor IDE的MCP设置文件位于:
- macOS:
~/.cursor/mcp.json或~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
方法1:使用Docker(推荐)
作为Docker容器运行。所有依赖性都包含在容器中,非常可靠。
{
"mcpServers": {
"gary-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v", "/Users/gary/Documents/workspace:/workspace:ro",
"-v", "/Users/gary/.aws:/root/.aws:ro",
"-v", "/Users/gary/.zshrc:/root/.zshrc:ro",
"-v", "/Users/gary/Documents/workspace/gary-mcp/.env:/app/.env:ro",
"-e", "WORKSPACE_PATH=/workspace",
"-e", "AWS_PROFILE=jongmun",
"-e", "SHELL_RC_PATH=/root/.zshrc",
"gary-mcp-server"
]
}
}
}注意事项:
- 必须先构建Docker映像:
docker build -t gary-mcp-server . .env如果有文件,可以将其作为卷装载。
方法2:如果您使用的是本地Python环境
直接在本地运行。在开发中或在没有Docker的情况下进行测试时非常有用。
{
"mcpServers": {
"gary-mcp": {
"command": "python3",
"args": [
"-m",
"src.server"
],
"cwd": "/Users/gary/Documents/workspace/gary-mcp",
"env": {
"WORKSPACE_PATH": "/Users/gary/Documents/workspace",
"AWS_PROFILE": "jongmun",
"SHELL_RC_PATH": "/Users/gary/.zshrc"
}
}
}
}注意事项:
- 必须在项目目录中安装依赖性:
uv pip install -e . WORKSPACE_PATH建议指定为绝对路径。
方法3:如果使用uv
通过uv自动管理和运行虚拟环境。
{
"mcpServers": {
"gary-mcp": {
"command": "uv",
"args": [
"run",
"--directory", "/Users/gary/Documents/workspace/gary-mcp",
"python",
"-m",
"src.server"
],
"env": {
"WORKSPACE_PATH": "/Users/gary/Documents/workspace",
"AWS_PROFILE": "jongmun",
"SHELL_RC_PATH": "/Users/gary/.zshrc"
}
}
}
}应用和验证设置
- 将JSON添加到配置文件:选择上述设置之一
~/.cursor/mcp.json添加到。 - 重新启动Cursor IDE:保存设置后,完全重新启动Cursor IDE。
- 验证连接:在Cursor左侧边栏的MCP部分中
gary-mcp验证服务器是否已连接。 - 使用工具:在AI聊天中
list_databases,run_query,read_document等工具可用。
设置环境变量
工作空间路径
WORKSPACE_PATH:浏览文档的工作空间路径
- docker:容器内部路径(例如: /workspace) - 本地:主机绝对路径(例如: /Users/gary/Documents/workspace)
AWS设置
AWS_PROFILE:要使用的AWS配置文件名称(默认为:jongmun)- AWS凭据
~/.aws目录或.zshrc将从中的环境变量自动加载。
Fly.io设置
- Fly.io凭证
.zshrc的FLY_*从环境变量中自动加载。
GitHub设置
- GitHub CLI
GH_*/GITHUB_*环境变量(GH_TOKEN,GITHUB_TOKEN等)。 gh auth login如果已通过认证,则无需进行其他设置即可使用。
数据库设置
.env可以将DB连接信息设置为文件或环境变量。- 有关详细信息,请访问 数据库连接错误 请参阅部分。
镜像官方文档
让LLM无需互联网即可使用官方文档 docs/manifest.yaml在本地缓存中定义的源。 type: git, type: archive 除此之外 type: http 您可以直接管理文档主URL,如AWS/Python/FastAPI/Docker/Kubenetes/Fly.io/PostgreSQL/Redis/Next.js/Tailwind CSS。
1.同步文档
# 모든 문서를 동기화
python scripts/sync_docs.py
# 특정 문서만 동기화 (예시)
python scripts/sync_docs.py python fastapi aws-main docker-main- 默认包含Python、FastAPI、React、TypeScript、Go、AWS、Docker、Kubindes、Fly.io、PostgreSQL、Redis、Next.js和Tailwind CSS文档。
- 结果
docs/mirror//存储为结构。.gitignore将从资料库提交目标中排除。
2.定义基于HTTP的文档
type: http 项目只需名称和URL即可定义。
- name: python-main
type: http
version: "3.x"
target: python/main
pages:
- url: https://docs.python.org/3/pages:在manifest条目中直接定义URL列表。path如果省略,将根据URL路径自动确定文件名。pages_file:必要时docs/您可以使用标准JSON/YAML文件单独管理URL列表。(测试示例为docs/pages/python-main.yaml注意)- 每个页面定义最少
url和要保存的相对路径(path)。如果没有路径,则基于URLindex.html等自动创建。 - 内置HTTP文档列表
- aws-main: https://docs.aws.amazon.com/ - python-main: https://docs.python.org/3/ - fastapi-main: https://fastapi.tiangolo.com/ - docker-main: https://docs.docker.com/ - kubernetes-main: https://kubernetes.io/docs/home/ - flyio-main: https://fly.io/docs/ - postgresql-main: https://www.postgresql.org/docs/current/index.html - redis-main: https://redis.io/docs/latest/ - nextjs-main: https://nextjs.org/docs - tailwindcss-main: https://tailwindcss.com/docs
3.MCP工具
sync_official_docs:在MCP内同步文档(names只能选择特定文档作为数组)。list_official_docs:查看当前缓存的文档列表和版本。search_official_docs:快速搜索镜像的官方文档(name可以将范围限制为)。
4.DocumentService集成
WORKSPACE_PATH=/Users/gary/Documents/workspace如果设置为 docs/mirror自动编制索引,因此现有 read_document/search_documents 也可以在工具中引用官方文档。添加新文档的步骤 docs/manifest.yaml将项目添加到 scripts/sync_docs.py运行即可。
可用工具
文档相关工具
read_document
读取工作空间中的文档文件。
参数:
file_path(必需):要读取的文档文件的路径
示例:
{
"file_path": "/workspace/my-project/README.md"
}list_workspace_projects
扫描工作空间中的项目列表。
示例:
{}search_documents
在工作空间中的文档中搜索。
参数:
query(必需):要搜索的关键字project_name(可选):仅在特定项目内搜索
示例:
{
"query": "FastAPI",
"project_name": "my-api-project"
}AWS相关工具
aws_cli_execute
运行AWS CLI命令(使用jongmun配置文件)。
参数:
service(必需):AWS服务名称(例如s3、ec2、lambda)operation(必需):任务名称(例如list、describe-instances)additional_args(可选):附加参数列表
示例:
{
"service": "s3",
"operation": "ls"
}aws_list_resources
查看AWS资源列表。
参数:
service(必需):AWS服务名称resource_type(可选):资源类型
示例:
{
"service": "ec2",
"resource_type": "instances"
}aws_get_account_info
查看AWS帐户信息。
示例:
{}Fly.io相关工具
flyio_list_apps
浏览Fly.io应用程序列表。
示例:
{}flyio_get_app_status
查询Fly.io应用程序的状态。
参数:
app_name(必需):应用程序名称
示例:
{
"app_name": "my-app"
}flyio_get_app_logs
查看Fly.io应用程序日志。
参数:
app_name(必需):应用程序名称lines(可选):要查询的日志行数(默认值:50)
示例:
{
"app_name": "my-app",
"lines": 100
}GitHub相关工具
github_cli_execute
直接运行GitHub CLI命令。
参数:
command(必需):要执行的子命令(例如:"repo","issue","pr")args(可选):附加参数数组
github_list_repos
查看存储库列表。
参数:
owner(可选):特定用户/组织visibility(可选):public,private,internallimit(可选):要查询的报告数(默认为20)sort(可选):排序依据(默认值)updated)
github_list_pull_requests
查询指定存储库的PR。
参数:
repo(必需):owner/repo格式state(可选):open,closed,all(默认open)limit(可选):结果数(默认值20)
github_list_issues
查询指定存储库中的问题。
参数:
repo(必需)state(可选):open,closed,alllimit(可选):结果数(默认值20)
PDF转换工具
markdown_to_pdf
将标记文件转换为PDF。
参数:
markdown_path(必需):要转换的标记文件路径output_path(可选):输出PDF文件路径css_path(可选):CSS样式文件路径
示例:
{
"markdown_path": "/workspace/my-project/README.md",
"output_path": "/workspace/my-project/README.pdf"
}代码分析工具
analyze_code_flow
分析项目的代码流。
参数:
project_path(必需):要分析的项目路径entry_point(可选):入口点文件
示例:
{
"project_path": "/workspace/my-project",
"entry_point": "main.py"
}find_related_code
查找关联的代码。
参数:
project_path(必需):要搜索的项目路径target_function(可选):要查找的函数名称target_class(可选):要查找的类名称target_import(可选):要查找的import模块名称
示例:
{
"project_path": "/workspace/my-project",
"target_function": "process_data"
}get_code_reusability
分析代码可重用性。
参数:
project_path(必需):要分析的项目路径language(可选):编程语言(默认为python)
示例:
{
"project_path": "/workspace/my-project",
"language": "python"
}数据库相关工具
list_databases
查看数据库列表。
参数:
db_name(可选):数据库名称connection_string(可选):直接连接字符串(例如:postgresql+asyncpg://user:pass@host:5432/db)use_dotenv(可选):使用.env文件(默认值:true)use_aws_secrets(可选):使用AWS Secrets Manageraws_secret_name(可选):AWS秘密名称use_github_secrets(可选):使用GitHub Secretsgithub_secret_name(可选):GitHub秘密名称github_repo(可选):GitHub存储库
示例:
{
"connection_string": "postgresql+asyncpg://user:pass@localhost:5432/mydb"
}describe_tables
查询表模式。
参数:
db_name(可选):数据库名称connection_string(可选):直接连接字符串database(可选):特定数据库名称use_dotenv,use_aws_secrets,aws_secret_name,use_github_secrets,github_secret_name,github_repo(可选):凭据源
示例:
{
"connection_string": "sqlite+aiosqlite:///./test.db"
}run_query
运行SQL查询(默认read-only,必要时指定read-write模式)。
参数:
query(必需):要执行的SQL查询db_name(可选):数据库名称connection_string(可选):直接连接字符串parameters(可选):查询参数(dict)limit(可选):限制结果行数(默认值:100)mode(可选):运行模式-read_only或read_write(默认值:read_only)use_dotenv,use_aws_secrets,aws_secret_name,use_github_secrets,github_secret_name,github_repo(可选):凭据源
示例:
{
"query": "SELECT * FROM users WHERE id = :id",
"parameters": {"id": 1},
"connection_string": "postgresql+asyncpg://user:pass@localhost:5432/mydb",
"mode": "read_only"
}注意事项:
- 默认模式为
read_only阻止INSERT/UPDATE/DELETE等写入操作。 - 如果需要写入操作
mode: "read_write"必须明确指定。 - 环境变量或
.env在文件中DATABASE_URL或者,您可以设置单个数据库参数。 - 您可以使用AWS Secrets Manager或GitHub Secrets安全地管理凭据。
官方文档工具
sync_official_docs
在本地同步官方文档。
参数:
names(可选):要同步的文档名称数组force(可选):未来扩展标志(默认为false)
list_official_docs
返回当前镜像的正式文档列表。
search_official_docs
在镜像文档中搜索关键字。
参数:
query(必需):搜索关键字name(可选):特定文档名称limit(可选):结果数量限制(默认为5)structured(可选):true基于语法/索引的部分搜索
resolve_library_id
使用库名称查询ID和元数据。
参数:
name(必需)react、next.js、typescript、python、spring、mysql
list_libraries
返回支持库列表。
参数:
category(선택):框架|语言|orm |数据库|云available_only(可选):仅过滤可同步项目
get_library_docs
以Context7样式查看库文档。
参数:
library_id(必需):是的/libraries/reactmode(可选):info|code(基本信息)topic(可选):特定主题关键字(例如hooks、routing)limit(可选):限制搜索结果(默认为5,在指定topic时应用)
MCP服务器集成
gary-mcp自动集成Cursor使用的其他MCP服务器。这使您可以在单个MCP服务器上使用所有工具。
自动集成
gary-mcp自动读取以下位置的配置文件,以整合外部MCP服务器:
~/.cursor/mcp.json~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json- 项目的
cursor-mcp-local.json
集成的MCP服务器
自动集成以下MCP服务器(如果在配置文件中定义):
- 顺序思维:思维过程工具(工具名称:
thinking_*) - chrome开发工具:调试Chrome(工具名称:
chrome_*) - 超级浏览器mcp:Web抓取/滚动/AI浏览器代理(工具名称:
hyperbrowser_*)
Hyperbrowser MCP工具
超级浏览器MCP提供了以下工具:
scrape_webpage:从网页提取内容(标记、截图等)crawl_webpages:浏览链接的页面,并以LLM友好格式提取extract_structured_data:将HTML转换为结构化JSONsearch_with_bing:运行Bing搜索browser_use_agent:使用Browser Use代理自动执行浏览器openai_computer_use_agent:使用OpenAI CUA模型实现通用自动化claude_computer_use_agent:使用Claude Computer Use处理复杂的浏览器create_profile/delete_profile/list_profiles:管理永久配置文件
命名空间
外部MCP服务器上的工具会自动添加命名空间前缀,以防止名称冲突。例如:
sequential-thinking的工具thinking_将添加前缀。chrome-devtools的工具chrome_将添加前缀。hyperbrowser-mcp的工具hyperbrowser_将添加前缀。
禁用集成
要禁用特定MCP服务器的集成,请从配置文件中删除该服务器或 gary-mcp 请只启用服务器。
项目结构
gary-mcp/
├── src/
│ ├── __init__.py
│ ├── server.py # 통합 MCP 서버 (레거시)
│ ├── servers/ # 독립적인 MCP 서버들
│ │ ├── __init__.py
│ │ ├── base_server.py # 공통 서버 베이스 클래스
│ │ ├── aws_server.py # AWS 서버
│ │ ├── flyio_server.py # Fly.io 서버
│ │ ├── github_server.py # GitHub 서버
│ │ ├── db_server.py # 데이터베이스 서버
│ │ ├── pdf_server.py # PDF 변환 서버
│ │ └── official_docs_server.py # 공식 문서 서버
│ ├── tools/ # 도구 서비스 클래스들
│ │ ├── __init__.py
│ │ ├── document_tool.py # 문서 참조 도구
│ │ ├── aws_tool.py # AWS CLI 도구
│ │ ├── flyio_tool.py # Fly.io 도구
│ │ ├── pdf_tool.py # 마크다운→PDF 변환
│ │ ├── code_analysis_tool.py # 코드 분석 도구
│ │ └── db_tool.py # 데이터베이스 접근 도구
│ ├── infrastructure/
│ │ └── db/
│ │ └── connection_manager.py # DB 연결 관리
│ └── utils/
│ ├── __init__.py
│ ├── file_utils.py # 파일 유틸리티
│ └── env_loader.py # 환경 변수/시크릿 로더
├── docker/ # 각 서버용 Dockerfile
│ ├── base.Dockerfile # 공통 베이스
│ ├── aws-cli-mcp.Dockerfile
│ ├── flyio-mcp.Dockerfile
│ ├── github-cli-mcp.Dockerfile
│ ├── db-mcp.Dockerfile
│ ├── pdf-mcp.Dockerfile
│ └── official-docs-mcp.Dockerfile
├── docker-compose.mcp.yml # 모든 서버를 위한 Docker Compose 설정
├── tests/
│ ├── __init__.py
│ ├── test_document_service.py
│ ├── test_pdf_service.py
│ ├── test_code_analysis_service.py
│ ├── test_cli_services.py
│ └── test_db_tool.py # DB 도구 테스트
├── pyproject.toml # uv 프로젝트 설정
├── Dockerfile # 통합 서버용 Docker 이미지 (레거시)
├── .dockerignore # Docker 빌드 제외 파일
├── .env.example # 환경 변수 예시
└── README.md # 이 파일技术堆栈
- Python 3.12:使用最新的Python版本
- 紫外线:快速的Python包管理器
- MCP-SDK:模型上下文协议Python SDK
- 异步:处理异步文件/进程
- SQLAlchemy:管理ORM和DB连接
- asyncpg/aiomysql/aiosqlite:异步DB驱动程序
- weasyprint:标注→PDF转换
- AWS-CLI:AWS资源管理
- Fly.io命令行界面:管理Fly.io应用程序
- 肉毒杆菌3:AWS Secrets Manager集成
- python dotenv加载:.env文件
故障射击
AWS CLI错误
问题:AWS CLI命令失败。
解决方法:
- 确保AWS配置文件设置正确:
aws configure list --profile jongmun- 确保在Docker容器中装载了AWS配置文件:
docker run -it --rm -v ~/.aws:/root/.aws:ro gary-mcp-server ls /root/.awsFly.io CLI错误
问题:Fly.io命令失败。
解决方法:
- 验证容器中是否安装了Fly.io CLI:
docker run -it --rm gary-mcp-server flyctl version- 可能需要Fly.io认证:
docker run -it --rm gary-mcp-server flyctl auth loginPDF转换错误
问题:标记→PDF转换失败。
解决方法:
- 验证是否已安装WeasyPrint依赖性库
- 验证标记下的文件路径是否正确
- 验证输出目录是否具有写入权限
工作空间访问错误
问题:无法访问工作空间文件。
解决方法:
- 确保正确设置了Docker卷装载
- 文件路径为
/workspace验证是否以开头(Docker容器内部路径)
数据库连接错误
问题:DB连接失败。
解决方法:
- 环境变量或
.env确保在文件中设置了正确的连接信息:
# .env 파일 예시
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname
# 또는
DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=user
DB_PASSWORD=password
DB_NAME=dbname- 使用AWS Secrets Manager:
- 验证IAM权限设置是否正确 - aws_secret_name验证是否正确
- 使用GitHub Secrets:
- gh auth login验证是否已通过 - 验证您是否具有访问存储库的权限
- 如果从Docker容器访问本地DB:
- --network host 启用选项或端口转发设置
同步官方文档时出错
问题: sync_official_docs 或 scripts/sync_docs.py 运行时失败。
解决方法:
git,tar,zip验证系统上是否安装了灯。- 检查互联网/代理设置,必要时
HTTPS_PROXY设置环境变量。 docs/manifest.yaml验证的URL和分支是否有效。- 初始化缓存的步骤
rm -rf docs/mirror docs/sources然后重新同步。
开发
本地开发首选参数
# 프로젝트 클론
git clone
cd gary-mcp
# uv 설치
pip install uv
# 의존성 설치
uv pip install -e .
# 서버 실행
python -m src.server代码样式
- 利用Python 3.12+功能
- 异步操作
async/await使用 - 建议使用类型提示
- 在函数和类中创建docstring
许可证
这个项目是为了个人使用而开发的。
贡献
这个项目是个人项目,但我们欢迎错误报告或改进建议。
