Перейти к основному содержимому
L

dsh-github

lornatang/dsh-github

Connects DeepSeek Harness to GitHub MCP tools for repositories, issues, pull requests, and Actions.

Установка

dsh plugin --profile web add github:lornatang/dsh-github

README


description: "GitHub's official MCP server inside a dsh profile: browser authorization, encrypted credentials, agent tools, write approval, and a connection settings page." kind: "package-bundle"

@lornatang/dsh-github

English | 中文

Summary

dsh-github connects a DeepSeek Harness profile to GitHub's hosted MCP server. It registers the server's tools for repository files, issues, pull requests and Actions, and adds a GitHub connection page to the Web client. Connect by authorizing in a browser, with an already authenticated GitHub CLI, or with a personal access token; the bridge asks DSH for approval before calls that are not marked read-only by the server. The package includes the public Client ID of its GitHub OAuth app. Available tools and account permissions are defined by GitHub.

Table of Contents


Use this package

The bridge owns the connection and registration; GitHub supplies the tool definitions and enforces the account's repository permissions. DSH's existing tool policies also apply. Install into the profile whose sessions should use GitHub:

dsh plugin --profile <name> add @lornatang/dsh-github
dsh plugin --profile <name> remove @lornatang/dsh-github

Versioned tarballs, when available, are listed in GitHub Releases. Restart DSH after adding or removing the bundle, then open Settings → GitHub in a Web profile.

Connect GitHub

Choose Connect with GitHub to open GitHub in a browser. Enter the one-time code shown in DSH, review the requested permissions, and approve the application; DSH completes the connection automatically. This does not require gh or a manually created token. GitHub's device flow requires the short code; it is not a personal access token. Cancelling a pending authorization preserves and restores the previous connection.

Choose Connect with GitHub CLI after installing gh and running gh auth login on the DSH host. The bridge reads the active github.com token through gh auth token; the token is not written to the profile. A saved connection remembers only that it should use gh again. This is GitHub CLI authentication, not an OAuth flow implemented by this plugin.

Alternatively, paste a GitHub personal access token into the password field and choose Connect with token. The bridge tests the connection before replacing the saved credential. It stores the token in an encrypted profile file; the settings page never returns it. Give the token the repository access and permissions needed for the requested work. If the connection fails, the previous saved credential is retained.

For a headless host, configure credentialSource: env and provide GITHUB_TOKEN to the DSH process, or set credentialSource: gh to use an already authenticated gh. The configured source takes precedence over the saved connection at startup.

What you get

SurfaceProvided by
mcp__github__<tool> for each tool GitHub advertises in the selected toolsetshost entry, src/bridge.ts
Approval request for a tool without readOnlyHint: truehost entry, src/index.ts
Settings → GitHub page with connection status and credential controlsclient entry, src/client/index.tsx
GET /plugins/github/status, POST /plugins/github/connect, POST /plugins/github/cancel and POST /plugins/github/disconnecthost entry, src/routes.ts
<profile>/data/dsh-github-<serverName>-<hash>.jsonhost entry, src/store.ts

The default toolsets are repos,issues,pull_requests,actions. Their actual tools can change on GitHub's side and are also affected by account permissions and GitHub policies. With suitable permissions, an agent can read files, create or update files, push a group of files, create a pull request, or inspect an issue and its checks. For large local repositories, normal Git operations may be a better fit than passing file contents through MCP tools.

Tools are named mcp__github__<name>. Characters outside letters, digits, hyphen and underscore become underscores; a changed or overlong name is shortened and receives a twelve-character SHA-256 suffix. The bridge uses the server's descriptions and input schemas. It validates declared structured output, renders text blocks as text, and represents other content blocks by type. A server error fails the call. Active GitHub credentials are redacted from tool output and error messages in a single pass when their exact values appear.

The bridge delegates to DSH's approval service for a tool unless the server marks it readOnlyHint: true; a missing hint is treated as requiring approval. Existing DSH policy decisions still apply. Read-only hints are provided by the configured MCP server, so use a trusted endpoint. The plugin does not grant GitHub permissions or approve calls on the user's behalf.

Credentials

The saved source and, when applicable, personal access or OAuth access and refresh tokens are stored in an AES-256-GCM envelope under <profile>/data/. Expiring OAuth access tokens are refreshed when needed. The file path is authenticated data. Decrypted sessions are type-checked on load and malformed fields are dropped. The 32-byte key comes from the operating-system credential store through @napi-rs/keyring, or from DSH_GITHUB_ENCRYPTION_KEY as standard Base64 for exactly 32 bytes. There is no plaintext fallback. On POSIX the file is restricted to 0600, the data directory to 0700, and symlinks, unsafe ownership and hard links are checked. On Windows, restrict the profile directory with ACLs.

For a headless host without an available credential store, set a persistent DSH_GITHUB_ENCRYPTION_KEY before saving a connection; keep the key and profile path across restarts. Disconnect removes the local encrypted file and keyring entry and unregisters tools; it does not revoke a GitHub token or sign out of gh. Use one DSH process per profile because this package does not coordinate concurrent writers.

Configuration

The bundled row sets the defaults below. A profile can override them in its patch:

# $DSH_HOME/profiles/web/cordis.patch.yml
- id: github
  config:
    serverName: github
    url: 'https://api.githubcopilot.com/mcp/'
    toolsets: 'repos,issues,pull_requests,actions'
    readOnly: false
    credentialSource: saved
    oauthClientId: 'Ov23liyuutYTU29KMjVg'
FieldDefaultMeaning
serverNamegithubTool namespace and credential identity; 1–64 letters, numbers, hyphens or underscores.
urlhttps://api.githubcopilot.com/mcp/GitHub MCP endpoint. HTTPS is required except for loopback HTTP.
toolCallTimeoutMs60000Connection, discovery and tool-call timeout in milliseconds.
toolsetsrepos,issues,pull_requests,actionsComma-separated toolsets passed in X-MCP-Toolsets.
readOnlyfalseSend X-MCP-Readonly: true to request only read tools.
credentialSourcesavedsaved, env (GITHUB_TOKEN), or gh (GitHub CLI).
oauthClientIdbundled app IDPublic client ID of the device-flow-enabled GitHub OAuth app. DSH_GITHUB_OAUTH_CLIENT_ID is used when this field is empty.
Browser sign-in setup for maintainers

The package includes the public Client ID of its registered OAuth app, so ordinary users do not need to register an app. To use a different app, register an OAuth app in GitHub Developer Settings, with this repository as its homepage and http://127.0.0.1/callback as its required callback URL, and enable Device Flow. The callback URL is not used by device flow. Override oauthClientId with that app's public Client ID, or set it to an empty string and provide DSH_GITHUB_OAUTH_CLIENT_ID to the DSH process. No client secret is needed for this flow. See GitHub's device-flow documentation.

The browser flow initially requests the OAuth scopes repo and read:org. These can grant broad access, including private repositories, subject to GitHub account and organization policies. GitHub shows the requested permissions before the user authorizes them. If a tool needs another scope, the tool call fails with a message and the settings page shows the requested scopes. Choose Connect with GitHub to review them on GitHub, then retry the operation. The plugin does not automatically retry writes, and DSH approval still applies.

Every request stays on the configured origin, with redirects not followed automatically. MCP responses are limited to 16 MiB and discovery to 8 MiB, 100 pages and 1,000 tools. Connection-route request bodies are limited to 8 KiB and must arrive within 5 seconds. Structured output is validated in a bounded pool of isolated workers; a validator that cannot be stopped is abandoned without blocking later calls.

Troubleshooting

  • Browser sign-in is unavailable — check that the configured OAuth app client ID is present and device flow is enabled. Restart DSH after changing the profile configuration or process environment.
  • Refreshed credentials could not be saved — keep DSH running and restore access to the profile's secure storage; the plugin retries saving on the next request. Closing DSH before the save succeeds may require browser authorization again.
  • GitHub CLI is unavailable or not authenticated — install gh on the DSH host and run gh auth login, or use a personal access token.
  • Connection fails or tools are missing — check network access to GitHub's MCP endpoint, account and organization policies, token permissions, selected toolsets, and the DSH log. Select a Connect button to retry.
  • Secure key storage is unavailable — unlock the system credential store or set DSH_GITHUB_ENCRYPTION_KEY to a persistent Base64-encoded 32-byte key.
  • Stored credentials cannot be decrypted — restore the original key and profile path, or remove the saved credential and reconnect.
  • A write is denied — check DSH's approval channel and policies as well as the GitHub account or token permissions.

Understand the implementation

Implementation internals — click to expand

The dsh.bundle.patch manifest inserts a host row; dsh.client exposes the Web settings section. apply creates a profile-specific store and bridge, binds the fenced routes, listens for DSH's pre-execution policy event, and starts the configured credential source. The bridge opens a Streamable HTTP MCP connection, discovers all tool pages, and registers one DSH tool per server definition. A failed or cancelled connection removes its registrations. Disconnect aborts outstanding requests before deleting saved state; unloading preserves state for the next start. The settings page polls connection status every three seconds while its tab is visible.

SourceContents
cordis.patch.ymlProfile row and defaults.
src/index.tsHost entry, route binding and approval policy.
src/config.tsConfiguration schema and defaults.
src/bridge.tsCredentials, MCP lifecycle, discovery and registered tools.
src/oauth.tsGitHub device authorization and access-token refresh.
src/transport.ts, src/response-limit.tsOrigin restriction, headers and response limits.
src/store.tsEncrypted credential file and host keyring.
src/routes.tsFenced connection routes.
src/output-validator.ts, src/output-validator-worker.tsPooled, worker-isolated validation of structured output with bounded cleanup.
src/client/index.tsxGitHub settings page.
tests/*.test.mjsMock MCP, credential, lifecycle and approval tests.

Further Exploration


Model Experience

The model sees the registered GitHub tool names, descriptions and input schemas. Results are returned as tool content; the settings page and credentials are not part of the model prompt. Requests to change GitHub can trigger DSH approval.

KV Cache effect

Connecting adds the discovered tool definitions to the request prefix; disconnecting removes them. A changed toolset or server catalog changes that prefix and can invalidate cached tokens after the first changed definition.

Known Limitations and Deferred Work

  • GitHub authorization policies — GitHub may impose account, organization or MCP access restrictions on the bundled OAuth app.
  • One connection per profile row — the Web routes use a fixed prefix, so the settings page assumes one GitHub bridge per profile.
  • Server-defined capabilities — tool names, schemas and read-only hints can change; server hints are not a security boundary for an untrusted endpoint.
  • No automatic recovery guarantee — if the connection closes or a request fails, reconnect from Settings or restart the configured headless source.
  • Credentials are tied to profile path and key — moving the profile or changing the key makes saved state unreadable. Disconnect does not revoke upstream credentials.
  • Plain-text rendering — non-text MCP content is represented by a type placeholder, not displayed as native media.

Dev Note

Working context for maintainers — click to expand

npm run build cleans and compiles the host and client, then bundles the client into lib/client.js. lib is committed. npm run typecheck checks both TypeScript projects; npm test builds and runs the mock-backed tests. npm run test:dsh installs the packed bundle into a temporary real DSH profile, checks its request fence and encrypted credential file, and exercises the settings page in Chrome when available. Set DSH_TEST_BINARY and CHROME_PATH for non-default locations. Node.js 22.19 or newer is required.

Похожие плагины