# SJTU MCP

English | [中文](./README_zh_CN.md)

![Claude Code](https://img.shields.io/badge/Claude%20Code-Supported-D97757)
![Codex](https://img.shields.io/badge/Codex-Supported-111827)
![SJTU API](https://img.shields.io/badge/SJTU%20API-OpenAI%20Compatible-2563EB)
![Version](https://img.shields.io/badge/Version-0.1.1-F59E0B)
![License](https://img.shields.io/badge/License-MIT-16A34A)

Turn your SJTU Zhiyuan No.1 API key into something you can actually use in `Claude Code` and `Codex`.

`SJTU MCP` wraps the SJTU-hosted model API as a local MCP server, so you can call these models directly from your normal agent workflow instead of hand-writing integration scripts over and over again.

## Why This Exists

Have you already applied for an SJTU Zhiyuan No.1 API key, but still found it hard to actually use in practice?

This project exists to solve exactly that problem:

- you already have API access
- you want to use it from `Claude Code` or `Codex`
- but the SJTU endpoint itself does not plug directly into these agent tools out of the box
- you do not want to rewrite the integration layer every time

## Highlights

- Supports `Claude Code`
- Supports `Codex`
- Supports both text and vision tasks
- Uses the SJTU OpenAI-compatible endpoint
- Fits naturally into existing MCP workflows

## Contents

- [Quick Start](#quick-start)
- [Environment Variables](#environment-variables)
- [Claude Code](#claude-code)
- [Codex](#codex)
- [Tools](#tools)
- [Example](#example)
- [Suggested Model Usage](#suggested-model-usage)
- [Notes](#notes)

## Quick Start

For most users, the simplest path is:

1. `git clone` this repo
2. `cd` into the project directory
3. install it once
4. add it as a global MCP server in `Claude Code` or `Codex`

```bash
git clone https://github.com/EternalWavee/sjtu-mcp.git
cd sjtu-mcp
pip install -e .
```

After installation, your MCP client can start the server automatically when needed. In normal use, you do not need to manually run the server command every time.

## Environment Variables

Required:

- `SJTU_API_KEY`

Optional:

- `SJTU_API_BASE_URL`
- `SJTU_DEFAULT_TEXT_MODEL`
- `SJTU_DEFAULT_REASONING_MODEL`
- `SJTU_DEFAULT_VISION_MODEL`
- `SJTU_REQUEST_TIMEOUT`

How to use them:

- [`.env.example`](./.env.example) is only a template showing which variables you need
- in actual use, put these values into the `env` block of your MCP configuration

## Claude Code

### Recommended: User Scope

Use this if you want `sjtu` available in all your `Claude Code` projects on this machine.

```powershell
claude mcp add sjtu --scope user -- python -m sjtu_mcp.server
```

Then:

1. open `~/.claude.json`
2. find the `sjtu` entry
3. copy the `env` section from [examples/claude-project.mcp.json](./examples/claude-project.mcp.json)
4. replace `your-api-key` with your real key

Verify:

```powershell
claude mcp list
```

### Project Scope

Use this if you want to commit a shared config into the repo for teammates.

How to use it:

1. copy [examples/claude-project.mcp.json](./examples/claude-project.mcp.json) into your project root as `.mcp.json`
2. replace `your-api-key` with your real key
3. adjust default models and timeout if needed

Windows / macOS example:

```json
{
  "mcpServers": {
    "sjtu": {
      "command": "python",
      "args": ["-m", "sjtu_mcp.server"],
      "env": {
        "SJTU_API_BASE_URL": "https://models.sjtu.edu.cn/api/v1",
        "SJTU_API_KEY": "your-api-key",
        "SJTU_DEFAULT_TEXT_MODEL": "deepseek-chat",
        "SJTU_DEFAULT_REASONING_MODEL": "deepseek-reasoner",
        "SJTU_DEFAULT_VISION_MODEL": "qwen3vl",
        "SJTU_REQUEST_TIMEOUT": "180"
      }
    }
  }
}
```

### Local Scope

Use this if you only want the server for the current project and do not want to commit the config.

```powershell
claude mcp add sjtu --scope local -- python -m sjtu_mcp.server
```

Then add the same `env` values to the corresponding MCP config entry.

## Codex

### Recommended: Global Setup

Use this if you want `sjtu` available in all your `Codex` projects on this machine.

```powershell
codex mcp add sjtu -- python -m sjtu_mcp.server
```

Then:

1. open your own `~/.codex/config.toml`
2. copy the content from [examples/codex-config.toml](./examples/codex-config.toml)
3. replace `your-api-key` with your real key
4. save and reload Codex or reload MCP

Verify:

```powershell
codex mcp list
```

### Config File Setup

If you already manage `~/.codex/config.toml` directly, you can use this template:

```toml
[mcp_servers.sjtu]
command = "python"
args = ["-m", "sjtu_mcp.server"]

[mcp_servers.sjtu.env]
SJTU_API_BASE_URL = "https://models.sjtu.edu.cn/api/v1"
SJTU_API_KEY = "your-api-key"
SJTU_DEFAULT_TEXT_MODEL = "deepseek-chat"
SJTU_DEFAULT_REASONING_MODEL = "deepseek-reasoner"
SJTU_DEFAULT_VISION_MODEL = "qwen3vl"
SJTU_REQUEST_TIMEOUT = "180"
```

## Tools

- `sjtu_models`
- `sjtu_text`
- `sjtu_vision`
- `sjtu_cheap_task`

## Example

### Input

```text
请调用 sjtu_vision 分析图片里面的内容 .assets/test.png
```

![test](./assets/test.png)

### Output

![answer](./assets/answer.png)

## Suggested Model Usage

- `deepseek-chat`
  - default for summaries, rewrites, cleanup, and low-risk text tasks
- `minimax` or `glm-5`
  - useful for lightweight rewriting, classification, or extraction
- `deepseek-reasoner`
  - better for tasks that truly need multi-step reasoning
- `qwen3vl`
  - a strong starting point for screenshots, OCR-style extraction, and image understanding
- `qwen3coder`
  - useful for code-adjacent utility tasks

## Notes

- This server currently assumes the SJTU endpoint supports OpenAI-compatible `/models` and `/chat/completions`.
- Local images are encoded as data URLs before sending.
- If your campus endpoint has model-specific quirks, extend the routing in [src/sjtu_mcp/server.py](./src/sjtu_mcp/server.py).