google-docs-mcp-server

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# oceanengine-mcp

[![CI](https://github.com/virgoC0der/go-mcp/actions/workflows/go.yml/badge.svg)](https://github.com/virgoC0der/go-mcp/actions/workflows/go.yml)

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
**Ocean Engine (巨量引擎)** — ByteDance's domestic advertising platform (巨量广告 /
巨量千川 / 本地推 / 星图). It lets AI agents query advertiser accounts, campaigns,
ads and performance reports — and, when explicitly enabled, adjust campaign
status and budget — over the standard MCP interface.

> **Why this exists.** The "general-purpose Go MCP SDK" question is settled: the
> [official `modelcontextprotocol/go-sdk`](https://github.com/modelcontextprotocol/go-sdk)
> (maintained with Google) and [`mark3labs/mcp-go`](https://github.com/mark3labs/mcp-go)
> own that space. The open niche is **vertical** MCP servers. Google Ads and Meta
> Ads already have MCP servers (and TikTok Ads has several), but **Ocean Engine —
> the domestic Chinese platform — has none.** This project fills that gap, and is
> built *on top of* the official SDK rather than reimplementing the protocol.

## Status

Early but functional. The MCP layer is fully working (verified end-to-end via the
in-memory transport and a stdio smoke test); the Ocean Engine client implements
the documented Marketing API endpoints. Hitting the live API requires a valid
`access_token` from the [Ocean Engine open platform](https://open.oceanengine.com/).

## Install

```bash
go install github.com/virgoC0der/go-mcp/cmd/oceanengine-mcp@latest
```

Or build from source:

```bash
make build   # produces ./bin/oceanengine-mcp
```

## Configuration

The server is configured via environment variables.

**Authentication** — choose one of two modes:

*Static token* (you manage refresh yourself):

| Variable | Description |
|---|---|
| `OCEANENGINE_ACCESS_TOKEN` | OAuth access token from the Ocean Engine open platform |

*Auto-refresh* (recommended — access tokens last ~1 day): supply app credentials
and a refresh token and the server refreshes transparently before expiry. Ocean
Engine **rotates the refresh token on every refresh**, so the server tracks the
latest one in memory for its lifetime.

| Variable | Required | Description |
|---|---|---|
| `OCEANENGINE_APP_ID` | yes | developer app ID (numeric) |
| `OCEANENGINE_APP_SECRET` | yes | developer app secret |
| `OCEANENGINE_REFRESH_TOKEN` | yes | OAuth refresh token (valid ~30 days) |
| `OCEANENGINE_ACCESS_TOKEN` | no | current access token, if you have a fresh one |
| `OCEANENGINE_ACCESS_TOKEN_EXPIRES_IN` | no | remaining lifetime in seconds; omit to refresh on first use |

Auto-refresh mode activates when `OCEANENGINE_APP_ID`, `OCEANENGINE_APP_SECRET`
and `OCEANENGINE_REFRESH_TOKEN` are all set; otherwise the server falls back to
the static `OCEANENGINE_ACCESS_TOKEN`.

> Persisting the rotated refresh token across restarts: when embedding the
> package, pass `oceanengine.WithOnRefresh(...)` to `NewRefreshingTokenSource` to
> receive each new token pair and store it.

**Other options:**

| Variable | Required | Description |
|---|---|---|
| `OCEANENGINE_BASE_URL` | no | API host override (defaults to `https://api.oceanengine.com`) |
| `OCEANENGINE_ENABLE_WRITES` | no | set to `1`/`true` to register the mutating tools (off by default) |

### Use with an MCP client

```json
{
  "mcpServers": {
    "oceanengine": {
      "command": "oceanengine-mcp",
      "env": { "OCEANENGINE_ACCESS_TOKEN": "your-token" }
    }
  }
}
```

## Tools

Read tools (always available):

| Tool | Ocean Engine endpoint | Purpose |
|---|---|---|
| `oceanengine_get_advertiser_info` | `GET /2/advertiser/info/` | account info by advertiser ID |
| `oceanengine_list_campaigns` | `GET /2/campaign/get/` | list campaigns (广告组), paginated |
| `oceanengine_list_ads` | `GET /2/ad/get/` | list ads (广告计划), paginated |
| `oceanengine_get_report` | `GET /2/report/ad/get/` | performance report by date range/dimensions |

Write tools (only when `OCEANENGINE_ENABLE_WRITES` is set — they mutate the live
account):

| Tool | Ocean Engine endpoint | Purpose |
|---|---|---|
| `oceanengine_update_campaign_status` | `POST /2/campaign/update/status/` | enable / disable / delete campaigns |
| `oceanengine_update_campaign_budget` | `POST /2/campaign/update/budget/` | set a campaign budget |

## Architecture

```
cmd/oceanengine-mcp     entrypoint: reads env, runs MCP over stdio
internal/mcpserver      registers tools on the official go-sdk; no protocol code
internal/oceanengine    thin Marketing API client (auth, envelope, endpoints)
```

The Ocean Engine client is deliberately thin and dependency-light. To broaden
endpoint coverage later, its methods can be backed by the much larger community
SDK [`bububa/oceanengine`](https://github.com/bububa/oceanengine) without touching
the MCP tool layer.

## Roadmap

- ~~OAuth token refresh~~ ✅ done (auto-refresh token source)
- 千川 (Qianchuan) e-commerce ad endpoints
- Broader report dimensions/metrics and async report export
- Optional `bububa/oceanengine` backend for full endpoint coverage

## Note on the repository name

This project currently lives in the `go-mcp` repository for historical reasons.
The intended home is a dedicated `oceanengine-mcp` repository — renaming the repo
(which preserves stars and history) updates the import path accordingly.

## Development

```bash
make test    # go test ./...
make vet     # go vet ./...
make build   # build the binary
```

## License

MIT — see [LICENSE](https://github.com/virgoC0der/go-mcp/tree/HEAD/LICENSE).

oceanengine-mcp

A Model Context Protocol (MCP) server for Ocean Engine (巨量引擎) — ByteDance's domestic advertising platform (巨量广告 / 巨量千川 / 本地推 / 星图). It lets AI agents query advertiser accounts, campaigns, ads and performance reports — and, when explicitly enabled, adjust campaign status and budget — over the standard MCP interface.

Why this exists. The "general-purpose Go MCP SDK" question is settled: the official modelcontextprotocol/go-sdk (maintained with Google) and mark3labs/mcp-go own that space. The open niche is vertical MCP servers. Google Ads and Meta Ads already have MCP servers (and TikTok Ads has several), but Ocean Engine — the domestic Chinese platform — has none. This project fills that gap, and is built on top of the official SDK rather than reimplementing the protocol.

Status

Early but functional. The MCP layer is fully working (verified end-to-end via the in-memory transport and a stdio smoke test); the Ocean Engine client implements the documented Marketing API endpoints. Hitting the live API requires a valid access_token from the Ocean Engine open platform.

Install

go install github.com/virgoC0der/go-mcp/cmd/oceanengine-mcp@latest

Or build from source:

make build   # produces ./bin/oceanengine-mcp

Configuration

The server is configured via environment variables.

Authentication — choose one of two modes:

Static token (you manage refresh yourself):

Variable	Description
`OCEANENGINE_ACCESS_TOKEN`	OAuth access token from the Ocean Engine open platform

Auto-refresh (recommended — access tokens last ~1 day): supply app credentials and a refresh token and the server refreshes transparently before expiry. Ocean Engine rotates the refresh token on every refresh, so the server tracks the latest one in memory for its lifetime.

Variable	Required	Description
`OCEANENGINE_APP_ID`	yes	developer app ID (numeric)
`OCEANENGINE_APP_SECRET`	yes	developer app secret
`OCEANENGINE_REFRESH_TOKEN`	yes	OAuth refresh token (valid ~30 days)
`OCEANENGINE_ACCESS_TOKEN`	no	current access token, if you have a fresh one
`OCEANENGINE_ACCESS_TOKEN_EXPIRES_IN`	no	remaining lifetime in seconds; omit to refresh on first use

Auto-refresh mode activates when OCEANENGINE_APP_ID, OCEANENGINE_APP_SECRET and OCEANENGINE_REFRESH_TOKEN are all set; otherwise the server falls back to the static OCEANENGINE_ACCESS_TOKEN.

Persisting the rotated refresh token across restarts: when embedding the package, pass oceanengine.WithOnRefresh(...) to NewRefreshingTokenSource to receive each new token pair and store it.

Other options:

Variable	Required	Description
`OCEANENGINE_BASE_URL`	no	API host override (defaults to `https://api.oceanengine.com`)
`OCEANENGINE_ENABLE_WRITES`	no	set to `1`/`true` to register the mutating tools (off by default)

Use with an MCP client

{
  "mcpServers": {
    "oceanengine": {
      "command": "oceanengine-mcp",
      "env": { "OCEANENGINE_ACCESS_TOKEN": "your-token" }
    }
  }
}

Tools

Read tools (always available):

Tool	Ocean Engine endpoint	Purpose
`oceanengine_get_advertiser_info`	`GET /2/advertiser/info/`	account info by advertiser ID
`oceanengine_list_campaigns`	`GET /2/campaign/get/`	list campaigns (广告组), paginated
`oceanengine_list_ads`	`GET /2/ad/get/`	list ads (广告计划), paginated
`oceanengine_get_report`	`GET /2/report/ad/get/`	performance report by date range/dimensions

Write tools (only when OCEANENGINE_ENABLE_WRITES is set — they mutate the live account):

Tool	Ocean Engine endpoint	Purpose
`oceanengine_update_campaign_status`	`POST /2/campaign/update/status/`	enable / disable / delete campaigns
`oceanengine_update_campaign_budget`	`POST /2/campaign/update/budget/`	set a campaign budget

Architecture

cmd/oceanengine-mcp     entrypoint: reads env, runs MCP over stdio
internal/mcpserver      registers tools on the official go-sdk; no protocol code
internal/oceanengine    thin Marketing API client (auth, envelope, endpoints)

The Ocean Engine client is deliberately thin and dependency-light. To broaden endpoint coverage later, its methods can be backed by the much larger community SDK bububa/oceanengine without touching the MCP tool layer.

Roadmap

~~OAuth token refresh~~ ✅ done (auto-refresh token source)
千川 (Qianchuan) e-commerce ad endpoints
Broader report dimensions/metrics and async report export
Optional bububa/oceanengine backend for full endpoint coverage

Note on the repository name

This project currently lives in the go-mcp repository for historical reasons. The intended home is a dedicated oceanengine-mcp repository — renaming the repo (which preserves stars and history) updates the import path accordingly.

Development

make test    # go test ./...
make vet     # go vet ./...
make build   # build the binary

License

MIT — see LICENSE.