Repository navigation
Commit 7a0481a
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
- packages/apps/connector-github
- src
- connectors
- flows
- test
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
0 commit comments