# 快速开始指南

## 安装依赖

### 使用 uv（推荐）

```bash
# 同步依赖（会自动创建虚拟环境）
uv sync

# 或者直接运行（会自动安装依赖）
uv run python server.py
```

### 使用 pip

```bash
pip install -r requirements.txt
```

## 准备 Schema 文件

在运行服务器之前，您需要将 OSIM 数据标准的 schema 文件复制到 `schemas/` 目录。

### 从参考项目复制（推荐）

如果您有访问参考项目的权限：

```bash
cp -r /Users/delin/git/osim-mcp-server/src/main/resources/schemas/* ./schemas/
```

### 从 OSIM 开源项目获取

从 [OSIM 开源工程](https://github.com/osim-project/osim) 的仓库中获取 schema 文件。

## 测试服务器

在运行完整服务器之前，可以先测试数据加载器：

```bash
python test_server.py
```

这将验证：
1. Schema 文件是否正确加载
2. 工具函数是否正常工作

## 运行服务器

### 使用 uv（推荐）

```bash
# 方式 1: 直接运行
uv run python server.py

# 方式 2: 使用启动脚本
./run.sh
```

### 使用 STDIO 传输（默认，用于 MCP 客户端）

```bash
# 使用 uv
uv run python server.py

# 或使用 pip 安装后
python server.py
```

### 使用 HTTP 传输（用于 Web 集成）

```bash
# 使用 uv
uv run python -c "from server import mcp; mcp.run(transport='http', host='127.0.0.1', port=8000)"

# 或使用 pip 安装后
python -c "from server import mcp; mcp.run(transport='http', host='127.0.0.1', port=8000)"
```

## 在 Claude Desktop 中配置

编辑 Claude Desktop 的配置文件（通常位于 `~/Library/Application Support/Claude/claude_desktop_config.json`），添加：

### 使用 uv（推荐）

```json
{
  "mcpServers": {
    "osim-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/Users/delin/git/osim-mcp-server-fastmcp/server.py"
      ]
    }
  }
}
```

### 使用 Python

```json
{
  "mcpServers": {
    "osim-mcp-server": {
      "command": "python",
      "args": [
        "/Users/delin/git/osim-mcp-server-fastmcp/server.py"
      ]
    }
  }
}
```

**注意**：请将路径替换为您实际的项目路径。

## 在 Cursor 中配置

在 Cursor 的 MCP 设置中添加服务器配置，服务器将通过 STDIO 方式与 Cursor 通信。

## 验证功能

服务器启动后，您可以使用以下 MCP 工具：

1. **list_schema_names**: 列出所有可用的 schema 名称
2. **describe_schemas**: 获取指定 schema 的描述信息
3. **get_schema**: 获取指定 schema 的完整字段定义

## 故障排除

### 问题：没有找到任何 schema

**解决方案**：确保 `schemas/` 目录中有 JSON 文件，并且文件格式正确。

### 问题：资源访问失败

**解决方案**：如果资源功能不工作，可能需要根据 fastmcp 的最新文档调整资源注册方式。当前实现使用 `@mcp.resource()` 装饰器，如果遇到问题，请参考 [FastMCP 文档](https://github.com/jlowin/fastmcp)。

### 问题：导入错误

**解决方案**：确保已安装所有依赖：
```bash
pip install --upgrade -r requirements.txt
```


