Skip to content

Commit 7a0481a

Browse files
feat(apps): connector-github, GitHub's remote MCP server as an open-edition connector app (E4 batch 1, GitHub half) (#28306)
Part of #28276 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:新增 npm 私有包 `packages/apps/connector-github`,一个开源版连接器应用:把 GitHub 的远程 MCP 服务器声明为 `mcp` 连接器(只读请求头,白名单只放 `search_issues`、`issue_read` 两个读工具),令牌经 `credentialRef` 由管理员提供、不进元数据;附两个用它的流程、上架文件和写给管理员的 README。 - 为什么改:这是卡上 E4 第一批的 GitHub 一半。Stripe 一半没有放进来:规范化脚本的 `--include-pattern` 只算出白名单、不裁剪文档,实测输出 63,317,655 字节、612 个操作(用到的只有 6 个),卡上要求的「脚本打印的 sha256」和「保持小」做不到同时成立,走法等卡上裁决,所以本 PR 用 `Part of` 不关卡。 - 风险与回滚:只新增一个私有包和锁文件里它的条目,不动任何已发布包、门禁或文档;回滚就是删掉这个目录再 `pnpm install`。 - 先看:① `packages/apps/connector-github/src/connectors/github.connector.ts`(URL、请求头、白名单、凭据引用);② `packages/apps/connector-github/test/boot.test.ts`(假 MCP 客户端上的整栈启动,走一遍管理员设凭据的路径);③ `packages/apps/connector-github/README.md` 的 Credentials 一节。 - 两分钟验证:`pnpm --filter @objectstack/connector-app-github test`,应看到 `Validation passed` 和 `Tests 10 passed (10)`。 - 需要你做的:无,席位落地。 ## What changes One new npm-private workspace package under the existing `packages/apps/*` glob, `@objectstack/connector-app-github` (`packages/apps/connector-github/`), and its entry in `pnpm-lock.yaml`. No other file changes. - **The connector** (`src/connectors/github.connector.ts`), written as recipe 2 of `skills/objectstack-automation/references/integration-recipes.md` teaches: `provider: 'mcp'`, http transport to `https://api.githubcopilot.com/mcp/` with the `X-MCP-Readonly: true` header, `providerConfig.include: ['search_issues', 'issue_read']`, and `auth: { type: 'bearer', credentialRef: 'GITHUB_MCP_TOKEN' }`. The URL, the read-only header and the `Authorization: Bearer TOKEN` form come from GitHub's own documentation (`github/github-mcp-server` at `f2a07cd1`, `docs/remote-server.md` and the README's remote configuration), and the `repo` scope both tools need comes from the same README's per-tool scope lines. - **Two flows that use it** (`src/flows/github.flows.ts`): `github_search_issues` (input `query`, output `search.content`) and `github_get_issue` (inputs `owner`, `repo`, `issue_number`, output `issue.content`). - **The stack** (`objectstack.config.ts`): `type: 'app'`, namespace `github`, `requires: ['automation']`, and the zero-argument `ConnectorMcpPlugin` in `plugins:`, the way the scaffolded template lists its executors. - **The listing file** (`objectstack.manifest.json`) and **the README** the listing points at. Its credentials section names `GITHUB_MCP_TOKEN`, where to get it and the permissions it needs, as the marketplace handbook asks. - **Validated by this repository's CI at HEAD.** The package's `test` script is `objectstack validate && vitest run`, so the run CI makes of `test` runs `os validate` first. No CI step runs a package's `validate` script on its own. ## Tests On head `cf30e616`: `pnpm --filter @objectstack/connector-app-github test` gives `Validation passed`, then `Test Files 2 passed (2)` and `Tests 10 passed (10)`. `pnpm --filter @objectstack/connector-app-github typecheck` exits 0. - `test/boot.test.ts` boots the app with `bootStack` (`@objectstack/verify`), which is how `objectstack serve` composes it. The only substitution is the MCP client, swapped in by plugin name through `extraPlugins`, so no call reaches GitHub. It checks the administrator's path in order: 1. With no credential set, `github_mcp` is `degraded`, the reason names `GITHUB_MCP_TOKEN`, and nothing is dialled. 2. A flow run in that state answers `400` `FLOW_FAILED`, the message names the reference, and nothing is dialled. 3. `PUT /api/v1/automation/connectors/credential-refs/GITHUB_MCP_TOKEN` brings the instance to `ready`. Its actions are exactly `issue_read` and `search_issues`, although the fake server also lists `issue_write`. The transport dialled is GitHub's URL with `X-MCP-Readonly: true` and `Authorization: Bearer` plus the fixture token. 4. Both flows dispatch their tool with the inputs they were given, through `POST /api/v1/automation/NAME/trigger`. - `test/listing.test.ts` checks the listing file. It parses against `TemplateManifestSchema`, its `manifestId` equals the stack's `manifest.id`, and it declares no key that publish ignores. The README's `## Credentials` section names every `credentialRef` the stack declares, and no connector carries a secret. - The vitest config aliases every workspace import to source and declares `OS_REGISTRY_LOG: 'warn'`. The suite's `[Registry]` lines went from 247 to 0. ## Acceptance notes - **The Stripe half is not in this PR.** It needs a decision, which the report on #28276 lays out. The measurement: `normalize-openapi --in` Stripe `spec3.json` at `51610f5f`, with an include pattern selecting 6 GET operations, writes 63,317,655 bytes holding all 612 operations, sha256 `0ea3c37a…`. `--include-pattern` computes the `include` list and trims nothing, and `--max-depth 0` still writes 6,070,551 bytes with all 612 operations. So "the packaged spec is the script's output, its sha256 in the README" and recipe 1's "trim the vendor's document to the operations the app calls" cannot both hold with the script as it is. - **A classic token that lacks the `repo` scope.** GitHub's server hides every tool the token's scopes do not cover (`docs/scope-filtering.md`), and an `include` entry the server does not list is a configuration fault. I probed this once, through `bootStack` against a fake server listing only `get_me`; the probe is not committed. With the value in the environment variable, the whole boot is refused. With the value in the credential store, the instance stays degraded and is told to "fix its declaration". A second `PUT` with a well-scoped value recovers it with no restart. The README states both outcomes as measured. - **No live call.** I hold no GitHub token for this, so the live call against GitHub's server is NOT MEASURED. - **The listing file is not covered by the repository gate.** `check:template-manifests` walks only `packages/create-objectstack/src/templates`, so this file is parsed by the package's own `listing.test.ts` instead. - The listing has no icon. The handbook makes an icon a requirement only for a marketplace submission, and listing generation is cloud-repository work. ## Verification <details><summary>Gate families that read this diff (60 of 60, all exit 0, head cf30e61)</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 60 commands (48 by path, 6 by change kind, 8 whole-tree). Every one ran with its exit code captured before any pipe. `--ran` reconciliation: `60 derived, 60 run, 0 NOT-MEASURED, 0 UNRUN`, a derived zero. On the first run (head `fbb7b6a2`), two gates were red on this package's test setup: `check:test-source-alias` (dist-resolved test imports) and `check:registry-log-declared` (a bootStack suite with no `OS_REGISTRY_LOG`). Both are fixed in `cf30e616` and green. None of the 60 assumes a published platform app: `check:published-files` and `check:changeset-fixed` both pass with the package private. </details> <details><summary>Not run locally</summary> `test:repo` and the repository-wide scans (`pnpm lint` first among them) belong to CI. The dogfood battery does not apply: the title has no `!` and there is no narrowing arm. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_017xRBcVBKAFk1ntXSjvPt7U)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 5055b10 commit 7a0481a

11 files changed

Lines changed: 568 additions & 0 deletions

File tree

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# GitHub
2+
3+
Search and read GitHub issues and pull requests from your flows. The app
4+
connects to GitHub's hosted MCP server (`https://api.githubcopilot.com/mcp/`)
5+
in read-only mode and exposes two of its read tools as connector actions.
6+
Nothing is written to GitHub.
7+
8+
## What it adds
9+
10+
- **A connector, `github_mcp`.** Its actions are `search_issues` (GitHub's
11+
issue and pull request search syntax) and `issue_read` (one issue's details).
12+
Any other tool the server offers stays out of your flows and agents.
13+
- **Two flows that use it**, ready to run or to copy:
14+
- `github_search_issues` takes a `query` (for example
15+
`repo:acme/app is:open label:bug`) and returns the matching issues as
16+
`search.content`.
17+
- `github_get_issue` takes `owner`, `repo` and `issue_number` and returns the
18+
issue as `issue.content`.
19+
20+
The app adds no objects, no sample data and no demo users. An install adds the
21+
connector and the two flows, and nothing else.
22+
23+
## Credentials
24+
25+
The app needs one credential. Until it is set, the `github_mcp` connector is
26+
listed as disconnected and its flows fail, naming the credential.
27+
28+
| Credential | What it is | Where to get it | Permissions it needs |
29+
|:---|:---|:---|:---|
30+
| `GITHUB_MCP_TOKEN` | A GitHub personal access token, sent to GitHub's MCP server as `Authorization: Bearer <token>` | GitHub → **Settings → Developer settings → Personal access tokens** (<https://github.com/settings/personal-access-tokens/new> for a fine-grained token) | Fine-grained token (GitHub's recommendation): access to the repositories you will search, with read-only **Issues** and **Pull requests** repository permissions; a repository owned by an organization also needs the organization to approve the token. Classic token: the `repo` scope, which both tools require |
31+
32+
Set the value in **Setup → Integrations → Connector Credentials**, or in the
33+
install dialog right after installing. An environment variable named
34+
`GITHUB_MCP_TOKEN` on the server takes precedence over a stored value.
35+
36+
Prefer a fine-grained token. With a classic token, GitHub's server hides every
37+
tool whose scope the token lacks. If that hides `search_issues` or
38+
`issue_read`, the connector does not start without them: a value set in
39+
**Connector Credentials** leaves `github_mcp` disconnected with a reason naming
40+
the missing tools, and a value set as the server environment variable stops the
41+
server from starting at all. Replace the token with one that carries the `repo`
42+
scope: a new value in **Connector Credentials** takes effect at once, a new
43+
environment variable at the next start.
44+
45+
The token is only ever sent to GitHub. It is never stored in the app's
46+
metadata.
47+
48+
## Running it
49+
50+
```bash
51+
curl -X POST "$OS_URL/api/v1/automation/github_search_issues/trigger" \
52+
-H "Authorization: Bearer $SESSION_TOKEN" -H 'Content-Type: application/json' \
53+
-d '{"params": {"query": "repo:acme/app is:open label:bug"}}'
54+
```
55+
56+
To use the answer elsewhere, add a `connector_action` node with
57+
`connectorId: 'github_mcp'` to your own flow and read `<nodeId>.content` in a
58+
later node.
59+
60+
## Limits
61+
62+
- Read only. The server is asked for read tools only (`X-MCP-Readonly: true`)
63+
and the connector allowlists two of them.
64+
- The token is a static personal token. Signing in with GitHub (OAuth) is not
65+
offered.
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import { defineStack } from '@objectstack/spec';
4+
import { ConnectorMcpPlugin } from '@objectstack/connector-mcp';
5+
import { GitHubMcpConnector } from './src/connectors/github.connector.js';
6+
import { allFlows } from './src/flows/github.flows.js';
7+
8+
/**
9+
* GitHub connector app — open edition (every key it uses runs on the open
10+
* tier), so it lives in this repository and is validated by its CI against
11+
* the runtime at HEAD. One declarative connector, two flows that use it; no
12+
* objects, no secret. The listing is `objectstack.manifest.json`, and the
13+
* README is what the administrator reads before installing.
14+
*/
15+
export default defineStack({
16+
manifest: {
17+
id: 'app.objectstack.connector-github',
18+
namespace: 'github',
19+
version: '0.1.0',
20+
type: 'app',
21+
name: 'GitHub',
22+
description: "Search and read GitHub issues from flows, through GitHub's remote MCP server.",
23+
engines: { protocol: '^18' },
24+
},
25+
26+
// `automation` materializes the `connectors:` entry at boot and runs the
27+
// flows; the executor below registers the `mcp` provider with it.
28+
requires: ['automation'],
29+
30+
// The generic `mcp` executor, zero-arg: it contributes the provider factory
31+
// only. The transport is http, so the stdio policy does not apply.
32+
plugins: [new ConnectorMcpPlugin()],
33+
34+
connectors: [GitHubMcpConnector],
35+
flows: allFlows,
36+
});
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"$schema": "https://schemas.objectstack.dev/template-manifest.json",
3+
"manifestId": "app.objectstack.connector-github",
4+
"name": "connector-github",
5+
"specVersion": "^18.0.0",
6+
"displayName": "GitHub",
7+
"description": "Search and read GitHub issues and pull requests from flows, through GitHub's remote MCP server. Read only.",
8+
"category": "devtools",
9+
"tags": ["github", "mcp", "connector", "issues"],
10+
"license": "Apache-2.0",
11+
"homepageUrl": "https://github.com/objectstack-ai/objectstack/tree/main/packages/apps/connector-github",
12+
"readmePath": "README.md"
13+
}
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "@objectstack/connector-app-github",
3+
"version": "0.1.0",
4+
"description": "GitHub connector app (open edition): GitHub's remote MCP server as a declarative `mcp` connector instance with a read-tool allowlist, authenticated by a personal access token the administrator supplies through the credential store.",
5+
"license": "Apache-2.0",
6+
"private": true,
7+
"type": "module",
8+
"main": "./objectstack.config.ts",
9+
"types": "./objectstack.config.ts",
10+
"exports": {
11+
".": "./objectstack.config.ts",
12+
"./objectstack.config": "./objectstack.config.ts"
13+
},
14+
"scripts": {
15+
"build": "objectstack build",
16+
"validate": "objectstack validate",
17+
"typecheck": "tsc --noEmit",
18+
"test": "objectstack validate && vitest run"
19+
},
20+
"dependencies": {
21+
"@objectstack/connector-mcp": "workspace:*",
22+
"@objectstack/spec": "workspace:*"
23+
},
24+
"devDependencies": {
25+
"@objectstack/cli": "workspace:*",
26+
"@objectstack/verify": "workspace:*",
27+
"@types/node": "^26.6.5",
28+
"typescript": "^6.0.3",
29+
"vitest": "^4.1.11"
30+
}
31+
}
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import { defineConnector } from '@objectstack/spec/integration';
4+
5+
/**
6+
* GitHub over its remote MCP server — recipe 2 of the integration recipes
7+
* (`skills/objectstack-automation/references/integration-recipes.md`): a
8+
* declarative `provider: 'mcp'` instance (ADR-0097) the `mcp` executor
9+
* materializes at boot by calling the server's `tools/list`.
10+
*
11+
* The server URL and the token header are GitHub's own
12+
* (github/github-mcp-server `docs/remote-server.md` and the README's remote
13+
* configuration): `https://api.githubcopilot.com/mcp/`, authenticated by
14+
* `Authorization: Bearer <personal access token>`. The `bearer` auth below is
15+
* folded into exactly that header by the executor; the token itself is never
16+
* in this file — `credentialRef` names it, and the administrator supplies the
17+
* value (an environment variable of that name, or Setup → Integrations →
18+
* Connector Credentials).
19+
*
20+
* `X-MCP-Readonly: true` asks the server to list only its read tools, and
21+
* `include` narrows those to the two this app's flows call. An `include`
22+
* entry the server does not list is refused at materialization, never
23+
* silently dropped.
24+
*/
25+
export const GitHubMcpConnector = defineConnector({
26+
name: 'github_mcp',
27+
label: 'GitHub (remote MCP)',
28+
type: 'api',
29+
description:
30+
"GitHub's remote MCP server, read tools only: issue search and single-issue reads, authenticated by a " +
31+
'personal access token the administrator supplies.',
32+
provider: 'mcp',
33+
providerConfig: {
34+
transport: {
35+
kind: 'http',
36+
url: 'https://api.githubcopilot.com/mcp/',
37+
headers: { 'X-MCP-Readonly': 'true' },
38+
},
39+
include: ['search_issues', 'issue_read'],
40+
},
41+
auth: { type: 'bearer', credentialRef: 'GITHUB_MCP_TOKEN' },
42+
});
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import { defineFlow } from '@objectstack/spec';
4+
5+
/**
6+
* Search GitHub issues and pull requests. Run it with
7+
* `POST /api/v1/automation/github_search_issues/trigger` and a body of
8+
* `{ "params": { "query": "repo:acme/app is:open label:bug" } }`; the tool's
9+
* answer is the run's `search.content` output.
10+
*/
11+
export const GitHubSearchIssuesFlow = defineFlow({
12+
name: 'github_search_issues',
13+
label: 'GitHub: search issues',
14+
description: "Searches issues and pull requests with GitHub's search syntax through the github_mcp connector.",
15+
type: 'autolaunched',
16+
status: 'active',
17+
variables: [
18+
{ name: 'query', type: 'text', isInput: true },
19+
{ name: 'search.content', type: 'json', isOutput: true },
20+
],
21+
nodes: [
22+
{ id: 'start', type: 'start', label: 'Start' },
23+
{
24+
id: 'search',
25+
type: 'connector_action',
26+
label: 'search_issues',
27+
connectorConfig: {
28+
connectorId: 'github_mcp',
29+
actionId: 'search_issues',
30+
input: { query: { dialect: 'cel', source: 'query' } },
31+
},
32+
},
33+
{ id: 'end', type: 'end', label: 'End' },
34+
],
35+
edges: [
36+
{ id: 'e1', source: 'start', target: 'search' },
37+
{ id: 'e2', source: 'search', target: 'end' },
38+
],
39+
});
40+
41+
/**
42+
* Read one issue. Run it with
43+
* `POST /api/v1/automation/github_get_issue/trigger` and a body of
44+
* `{ "params": { "owner": "acme", "repo": "app", "issue_number": 42 } }`; the
45+
* issue is the run's `issue.content` output.
46+
*/
47+
export const GitHubGetIssueFlow = defineFlow({
48+
name: 'github_get_issue',
49+
label: 'GitHub: get issue',
50+
description: 'Reads one issue (title, state, body, labels) through the github_mcp connector.',
51+
type: 'autolaunched',
52+
status: 'active',
53+
variables: [
54+
{ name: 'owner', type: 'text', isInput: true },
55+
{ name: 'repo', type: 'text', isInput: true },
56+
{ name: 'issue_number', type: 'number', isInput: true },
57+
{ name: 'issue.content', type: 'json', isOutput: true },
58+
],
59+
nodes: [
60+
{ id: 'start', type: 'start', label: 'Start' },
61+
{
62+
id: 'issue',
63+
type: 'connector_action',
64+
label: 'issue_read',
65+
connectorConfig: {
66+
connectorId: 'github_mcp',
67+
actionId: 'issue_read',
68+
input: {
69+
method: 'get',
70+
owner: { dialect: 'cel', source: 'owner' },
71+
repo: { dialect: 'cel', source: 'repo' },
72+
issue_number: { dialect: 'cel', source: 'issue_number' },
73+
},
74+
},
75+
},
76+
{ id: 'end', type: 'end', label: 'End' },
77+
],
78+
edges: [
79+
{ id: 'e1', source: 'start', target: 'issue' },
80+
{ id: 'e2', source: 'issue', target: 'end' },
81+
],
82+
});
83+
84+
export const allFlows = [GitHubSearchIssuesFlow, GitHubGetIssueFlow];

0 commit comments

Comments
 (0)