diff --git a/.codex/hooks.json b/.codex/hooks.json deleted file mode 100644 index 5cd1e72..0000000 --- a/.codex/hooks.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "SessionStart": [ - { - "command": ["bash", "./plugin-scripts/session-start.sh"], - "timeout": 30 - } - ], - "PreToolUse": [ - { - "match": { "tool": "shell" }, - "command": ["bash", "./plugin-scripts/block-delete-operations.sh"], - "timeout": 5 - }, - { - "match": { "tool": "shell" }, - "command": ["bash", "./hooks/auto-approve-tfy-api.sh"], - "timeout": 5 - }, - { - "match": { "tool": "shell" }, - "command": ["bash", "./plugin-scripts/pre-tool-secret-scan.sh"], - "timeout": 5 - } - ] -} diff --git a/.gitignore b/.gitignore index 6d2e2da..3152114 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,6 @@ __pycache__/ .augment/ .claude/ .codex/ -!/.codex/hooks.json .codebuddy/ .commandcode/ .continue/ diff --git a/README.md b/README.md index 5f4bf17..c1873e2 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,28 @@ This is the official skills repo — it lets your coding agent set up and manage the gateway through plain English. -## Setup +## Installation -Install the skills: +### Quick Install + +Using `npx skills`: + +Local (current project): + +```bash +npx skills add truefoundry/skills --skill '*' --yes +``` + +Global (all projects): + +```bash +npx skills add truefoundry/skills --skill '*' --yes --global +``` + +To link skills to a specific agent, for example Claude Code: ```bash -npx skills add truefoundry/skills +npx skills add truefoundry/skills --agent claude-code --skill '*' --yes --global ``` Then open Claude Code, Codex, or Cursor and say: diff --git a/install.md b/install.md index 80ea6f6..3c59978 100644 --- a/install.md +++ b/install.md @@ -1,5 +1,29 @@ # TrueFoundry Skills Install +## Installation + +### Quick Install + +Using `npx skills`: + +Local (current project): + +```bash +npx skills add truefoundry/skills --skill '*' --yes +``` + +Global (all projects): + +```bash +npx skills add truefoundry/skills --skill '*' --yes --global +``` + +To link skills to a specific agent, for example Claude Code: + +```bash +npx skills add truefoundry/skills --agent claude-code --skill '*' --yes --global +``` + Paste this into Claude Code, Codex, Cursor, or any coding agent that can read a URL: > Read https://raw.githubusercontent.com/truefoundry/skills/main/install.md and follow the instructions to register with TrueFoundry. diff --git a/skills/gateway/references/schemas/mcp-server.md b/skills/gateway/references/schemas/mcp-server.md index 63223f0..af2bdd2 100644 --- a/skills/gateway/references/schemas/mcp-server.md +++ b/skills/gateway/references/schemas/mcp-server.md @@ -1,11 +1,18 @@ --- name: mcp-server-schema -description: Complete schema reference for MCP server types -- remote, OpenAPI, and virtual -- including transport, auth, TLS, and tool filtering configurations. +description: Compact schema reference for MCP Gateway manifests. For full YAML examples, use the MCP servers skill references. --- # MCP Server Schema Reference -Three MCP server types can be registered with the gateway: remote endpoints, OpenAPI spec wrappers, and virtual (composite) servers. +This file is a compact schema index for gateway-related work. The canonical MCP Gateway workflow lives in `skills/mcp-servers/SKILL.md`. + +For detailed examples, read: + +- `../../../mcp-servers/references/mcp-yaml-variations.md` +- `../../../mcp-servers/references/mcp-gateway-ui-flows.md` + +Treat the live dashboard `Apply using YAML` preview as the source of truth when it differs from static examples. ## Fetch Existing Config @@ -17,381 +24,124 @@ $TFY_API_SH GET /api/svc/v1/mcp-servers $TFY_API_SH GET /api/svc/v1/mcp-servers/SERVER_ID ``` -### Example Response - -```json -{ - "data": [ - { - "id": "mcp-abc123", - "name": "my-remote-server", - "type": "mcp-server/remote", - "description": "Production analytics MCP server", - "url": "https://analytics.example.com/mcp", - "transport": "streamable-http", - "auth_data": { - "type": "header", - "headers": { - "Authorization": "Bearer tfy-secret://my-org:mcp-secrets:api-token" - } - }, - "collaborators": [ - { "subject": "user:jane@example.com", "role_id": "admin" } - ], - "tags": ["analytics", "production"] - }, - { - "id": "mcp-def456", - "name": "dev-tools", - "type": "mcp-server/virtual", - "description": "Composite server", - "servers": [ ... ] - }, - { - "id": "mcp-ghi789", - "name": "petstore-api", - "type": "mcp-server/openapi", - "description": "Petstore API exposed as MCP tools", - "spec": { "type": "remote", "url": "https://internal-api.example.com/openapi.json" } - } - ] -} -``` +## Common Fields ---- +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `name` | string | Yes | Unique MCP server name | +| `type` | string | Yes | `mcp-server/remote`, `mcp-server/openapi`, or `mcp-server/virtual` | +| `description` | string | Yes | Human-readable purpose | +| `collaborators` | array | Yes | Access grants | +| `tags` | string[] | No | Organization/filtering metadata | -## Schema Reference +Collaborator subjects: -### Common Fields (All MCP Server Types) +- `user:` +- `team:` +- `serviceaccount:` +- `virtualaccount:` -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Unique server name | -| `type` | string | Yes | `"mcp-server/remote"`, `"mcp-server/openapi"`, or `"mcp-server/virtual"` | -| `description` | string | No | Human-readable description | -| `collaborators` | array | No | Access control entries | -| `tags` | string[] | No | Tags for organization and filtering | +Use `role_id: mcp-server-manager` for management access unless the user requests another role. -### Collaborator Entry +## Server Types -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `subject` | string | Yes | `user:` or `team:` | -| `role_id` | string | Yes | `"admin"` or `"viewer"` | +### Remote ---- +Connects to an existing HTTP MCP endpoint. -## Type 1: `mcp-server/remote` +Required fields: -Connects to an existing MCP endpoint over HTTP. +- `name` +- `description` +- `type: mcp-server/remote` +- `url` +- `collaborators` -### Fields +Optional fields include `auth_data`, `tls_settings`, and `tags`. -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Unique server name | -| `type` | string | Yes | `"mcp-server/remote"` | -| `url` | string | Yes | MCP endpoint URL | -| `transport` | string | Yes | `"streamable-http"` or `"sse"` | -| `auth_data` | object | No | Authentication config (see Auth Options) | -| `tls_settings` | object | No | TLS configuration (see TLS Settings) | -| `description` | string | No | Human-readable description | -| `collaborators` | array | No | Access control entries | -| `tags` | string[] | No | Tags for organization | +### OpenAPI -Internal URL pattern for cluster services: `http://{service-name}.{namespace}.svc.cluster.local:{port}/mcp` +Wraps OpenAPI operations as MCP tools. -### Auth Options +Required fields: -#### `header` -- Static Header Auth +- `name` +- `description` +- `type: mcp-server/openapi` +- `spec` +- `collaborators` -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"header"` | -| `headers` | object | Yes | Key-value pairs of headers to send | +Use only trusted remote spec URLs. Prefer inline specs for sensitive private APIs. -```yaml -auth_data: - type: header - headers: - Authorization: "Bearer tfy-secret://my-org:mcp-secrets:api-token" -``` +### Virtual -All header values containing credentials MUST use `tfy-secret://` references. - -#### `oauth2` -- OAuth2 Auth - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"oauth2"` | -| `authorization_url` | string | Yes | OAuth2 authorization endpoint | -| `token_url` | string | Yes | OAuth2 token endpoint | -| `client_id` | string | Yes | OAuth2 client ID | -| `client_secret` | string | Yes | `tfy-secret://` reference to client secret | -| `jwt_source` | string | No | Token field to use (e.g., `"access_token"`) | -| `scopes` | string[] | No | OAuth2 scopes to request | -| `pkce` | boolean | No | Enable PKCE (`true`/`false`) | -| `dynamic_client_registration` | object | No | Dynamic client registration config | - -```yaml -auth_data: - type: oauth2 - authorization_url: https://auth.example.com/authorize - token_url: https://auth.example.com/token - client_id: my-client-id - client_secret: tfy-secret://my-org:mcp-secrets:oauth-client-secret - jwt_source: access_token - scopes: - - read - - write - pkce: true -``` +Composes existing MCP servers into one virtual server. -##### Dynamic Client Registration (Optional) +Required fields: -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `registration_endpoint` | string | Yes | Registration URL | -| `initial_access_token` | string | No | `tfy-secret://` reference to registration token | +- `name` +- `description` +- `type: mcp-server/virtual` +- `servers` +- `collaborators` -```yaml -dynamic_client_registration: - registration_endpoint: https://auth.example.com/register - initial_access_token: tfy-secret://my-org:mcp-secrets:registration-token -``` +Each `servers[]` entry needs `name`. Add `enabled_tools` only when exposing a selected subset. Omit `enabled_tools` when exposing every tool from that source. -#### `passthrough` -- Forward TFY Credentials +### Hosted STDIO-Derived -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"passthrough"` | +The UI starts from an `mcpServers` JSON object with `command`, `args`, and optional `env`, then generates the gateway manifest. Use the generated YAML preview as the manifest source of truth. -```yaml -auth_data: - type: passthrough -``` +## Auth Data -Forwards TrueFoundry user credentials to the downstream MCP server. +No auth means omit `auth_data`. -### TLS Settings (Optional) +Supported auth modes: -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `ca_cert` | string | No | `tfy-secret://` reference to CA certificate PEM | -| `insecure_skip_verify` | boolean | No | Skip TLS verification (`false` recommended) | +| UI mode | YAML shape | +|---------|------------| +| API Key / shared credentials | `auth_data.type: header`, `auth_level: global`, `headers` | +| API Key / individual credentials | `auth_data.type: header`, `auth_level: per_user`, `headers` with placeholders | +| OAuth2 authorization code | `auth_data.type: oauth2`, `grant_type: authorization_code` | +| OAuth2 client credentials | `auth_data.type: oauth2`, `grant_type: client_credentials` | +| Token passthrough | `auth_data.type: passthrough` | -```yaml -tls_settings: - ca_cert: tfy-secret://my-org:mcp-secrets:ca-cert-pem - insecure_skip_verify: false -``` +Use `tfy-secret://...` references for shared real credentials. Use placeholders such as `{{API_KEY}}` for per-user values. -### Full Remote Server Example - -```yaml -name: my-remote-server -type: mcp-server/remote -description: Production analytics MCP server -url: https://analytics.example.com/mcp -transport: streamable-http -auth_data: - type: header - headers: - Authorization: "Bearer tfy-secret://my-org:mcp-secrets:api-token" -tls_settings: - ca_cert: tfy-secret://my-org:mcp-secrets:ca-cert-pem - insecure_skip_verify: false -collaborators: - - subject: user:jane@example.com - role_id: admin -tags: - - analytics - - production -``` - ---- - -## Type 2: `mcp-server/openapi` - -Wraps an OpenAPI specification as an MCP server. Operations in the spec become MCP tools (max 30 tools). +Read `../../../mcp-servers/references/mcp-yaml-variations.md` for concrete auth examples. -### Fields +## Tool Enablement -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Unique server name | -| `type` | string | Yes | `"mcp-server/openapi"` | -| `spec` | object | Yes | OpenAPI spec source (see Spec Options) | -| `auth_data` | object | No | Authentication config (same options as remote) | -| `description` | string | No | Human-readable description | -| `collaborators` | array | No | Access control entries | +For normal remote/OpenAPI servers: -### Spec Options +1. Fetch the current server config. +2. Inspect the API response or UI YAML preview for the tool-selection shape. +3. Modify only the requested tool-selection fields. +4. Preserve URL/spec, auth, TLS, collaborators, tags, and unrelated fields. -#### Remote Spec +Do not guess field names for normal-server tool filtering. -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"remote"` | -| `url` | string | Yes | URL to the OpenAPI JSON/YAML spec | +For virtual servers, use `servers[].enabled_tools`. -```yaml -spec: - type: remote - url: https://internal-api.example.com/openapi.json -``` - -> **Security:** Remote specs are fetched at runtime and auto-converted into MCP tools. Only use trusted, verified spec URLs. - -#### Inline Spec - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"inline"` | -| `content` | string | Yes | Full OpenAPI spec as a YAML or JSON string | - -```yaml -spec: - type: inline - content: | - openapi: "3.0.0" - info: - title: Internal API - version: "1.0" - paths: - /health: - get: - operationId: healthCheck - summary: Check service health - responses: - "200": - description: OK -``` +## Generate And Validate -Prefer `inline` for sensitive environments to eliminate runtime dependency on external endpoints. - -### Full OpenAPI Server Example (Remote Spec) - -```yaml -name: petstore-api -type: mcp-server/openapi -description: Petstore API exposed as MCP tools -spec: - type: remote - url: https://internal-api.example.com/openapi.json -collaborators: - - subject: user:dev@example.com - role_id: viewer -``` - ---- - -## Type 3: `mcp-server/virtual` - -Composes multiple registered MCP servers into a single virtual server. Each sub-server can expose all or a filtered subset of its tools. - -### Fields - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Unique server name | -| `type` | string | Yes | `"mcp-server/virtual"` | -| `servers` | array | Yes | Array of sub-server references | -| `description` | string | No | Human-readable description | -| `collaborators` | array | No | Access control entries | - -### Sub-Server Entry - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Name of an already-registered MCP server | -| `enabled_tools` | string[] | No | Subset of tools to expose. Omit to expose all tools. | - -```yaml -servers: - - name: code-analysis-server - enabled_tools: - - lint - - format - - analyze - - name: deployment-server - enabled_tools: - - deploy - - rollback -``` - -### Full Virtual Server Example - -```yaml -name: dev-tools -type: mcp-server/virtual -description: Composite server combining code analysis and deployment tools -servers: - - name: code-analysis-server - enabled_tools: - - lint - - format - - analyze - - name: deployment-server - enabled_tools: - - deploy - - rollback -collaborators: - - subject: team:platform-eng - role_id: viewer -``` - ---- - -## Generate and Validate Workflow - -### 1. Write YAML manifest - -Choose the appropriate type (`remote`, `openapi`, or `virtual`) and fill in all required fields per the schemas above. - -### 2. Validate (dry run) +Dry-run first: ```bash tfy apply -f mcp-server.yaml --dry-run --show-diff ``` -### 3. Fix any errors - -Common issues: -- Invalid `transport` value (must be `"streamable-http"` or `"sse"`) -- Missing `auth_data` fields for OAuth2 (requires `authorization_url`, `token_url`, `client_id`, `client_secret`) -- Raw credentials in `headers` instead of `tfy-secret://` references -- OpenAPI spec exceeds 30 tools limit -- Virtual server references a `name` that does not match any registered MCP server -- Inline spec has YAML syntax errors - -### 4. Apply +Apply only after explicit confirmation: ```bash tfy apply -f mcp-server.yaml ``` -Or via direct API: - -```bash -$TFY_API_SH PUT /api/svc/v1/apps "$(cat mcp-server.yaml | yq -o json)" -``` - ---- +Common checks: -## Checklist - -- [ ] Server `name` is unique -- [ ] `type` is one of: `mcp-server/remote`, `mcp-server/openapi`, `mcp-server/virtual` -- [ ] **Remote:** `url` is set and reachable from the cluster -- [ ] **Remote:** `transport` is `"streamable-http"` or `"sse"` -- [ ] **Remote:** All credential values in `auth_data.headers` use `tfy-secret://` references -- [ ] **Remote:** OAuth2 includes all required fields (`authorization_url`, `token_url`, `client_id`, `client_secret`) -- [ ] **Remote:** TLS `ca_cert` uses a `tfy-secret://` reference if specified -- [ ] **OpenAPI:** `spec.type` is `"remote"` or `"inline"` -- [ ] **OpenAPI:** Remote spec URL is trusted and verified by the user -- [ ] **OpenAPI:** Spec produces at most 30 tools -- [ ] **Virtual:** All servers listed in `servers[].name` are already registered -- [ ] **Virtual:** `enabled_tools` lists only valid tool names from the referenced server -- [ ] Collaborators are set appropriately for access control -- [ ] Dry-run passes: `tfy apply -f manifest.yaml --dry-run --show-diff` +- `name`, `description`, `type`, and collaborators are set. +- Auth disabled omits `auth_data`. +- API key auth includes `type: header`, `auth_level`, and headers. +- OAuth2 auth includes the right `grant_type`, `token_url`, and `jwt_source`. +- Shared secrets use `tfy-secret://...`. +- Virtual source servers and `enabled_tools` are valid. +- YAML preview and hand-written manifest agree; prefer the gateway preview. diff --git a/skills/integrate-gateway/install.md b/skills/integrate-gateway/install.md index 9adaac1..423c51b 100644 --- a/skills/integrate-gateway/install.md +++ b/skills/integrate-gateway/install.md @@ -5,13 +5,13 @@ Integrate your codebase with TrueFoundry AI Gateway — scan, plan, migrate, and ## Quickest path ```bash -npx skills add truefoundry/skills -s integrate-gateway +npx skills add truefoundry/skills --skill integrate-gateway --yes ``` This installs only the integrate-gateway skill. To install all TrueFoundry skills: ```bash -npx skills add truefoundry/skills --all +npx skills add truefoundry/skills --skill '*' --yes ``` ## Claude Code (plugin install) @@ -25,7 +25,7 @@ This loads all skills including integrate-gateway. ## Cursor ```bash -npx skills add truefoundry/skills -g -a cursor -s integrate-gateway -y +npx skills add truefoundry/skills --agent cursor --skill integrate-gateway --yes --global ``` ## Manual (any agent) diff --git a/skills/mcp-servers/SKILL.md b/skills/mcp-servers/SKILL.md index 9a16d2f..3151761 100644 --- a/skills/mcp-servers/SKILL.md +++ b/skills/mcp-servers/SKILL.md @@ -1,6 +1,6 @@ --- name: truefoundry-mcp-servers -description: Manages TrueFoundry MCP server registry entries. Covers listing, creating, and updating remote, virtual, OpenAPI-backed, and hosted stdio MCP servers. Delete operations are manual dashboard-only. +description: Manages TrueFoundry MCP Gateway server registry entries. Covers listing, creating, updating, tool selection, access control, and client attachment for remote, official remote, virtual, hosted STDIO, and OpenAPI-backed MCP servers. Delete operations are manual dashboard-only. license: MIT compatibility: Requires Bash, curl, tfy CLI, and access to a TrueFoundry tenant allowed-tools: Bash(*/tfy-api.sh *) Bash(tfy*) Bash(curl*) Bash(python*) @@ -14,161 +14,223 @@ Manage MCP servers in TrueFoundry AI Gateway. Use this skill when the user wants to: -- List registered MCP servers. -- Add a remote MCP server. -- Add a virtual MCP server composed from existing servers. -- Add an OpenAPI-backed MCP server. -- Register a hosted stdio MCP server after it is exposed over HTTP. -- Update an existing MCP server by fetching its current config, editing it, and re-applying the full manifest. +- List MCP servers attached to a gateway. +- Connect remote or official remote MCP servers. +- Create virtual MCP servers from tools across multiple source servers. +- Create hosted STDIO MCP servers from `mcpServers` JSON. +- Import OpenAPI specs as MCP servers. +- Enable or disable tools. +- Update auth, access, metadata, endpoint/spec, or selected tools. +- Add MCP servers to clients such as Cursor, VS Code, Claude Code, Python, TypeScript, Windsurf, or Codex. -Do not manage secrets here. Use the `platform` skill for secret groups and secret references. - -Do not delete MCP servers from the agent. If deletion is requested, direct the user to the TrueFoundry dashboard. +Do not delete MCP servers or remove collaborators from the agent. Route those requests to the TrueFoundry dashboard. -## Preflight +## Reference Map + +Load only the reference needed for the user's task: + +| Task | Reference | +|------|-----------| +| Browser/UI operation, click paths, form fields, add-to-client modal | [references/mcp-gateway-ui-flows.md](references/mcp-gateway-ui-flows.md) | +| YAML examples for auth modes, server types, virtual tool selection, OpenAPI, hosted STDIO | [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) | + +Treat the live dashboard `Apply using YAML` preview as the source of truth when it differs from examples. -1. Verify `tfy login` is complete. If not, use `truefoundry-onboard`. -2. Verify the target tenant from `TFY_BASE_URL`/`TFY_HOST`. -3. Confirm the workspace or registry scope with the user before applying changes. -4. Use `tfy-secret://...` references for any auth material. +## Safety Rules -Before final `tfy apply`, always show: +- Verify `tfy login` is complete. If not, use `truefoundry-onboard`. +- Verify the target tenant from `TFY_BASE_URL`/`TFY_HOST`. +- Confirm the workspace or registry scope with the user before applying changes. +- Use `mcp-server-manager` as the default role unless the user requests another role. +- Use collaborator subjects as `user:`, `team:`, `serviceaccount:`, or `virtualaccount:`. +- Use `tfy-secret://...` references for shared credentials whenever possible. +- Never print, paste, or reveal real credentials unless the user explicitly asks and accepts exposure. +- Do not call DELETE APIs, destructive CLI commands, or collaborator-removal flows. + +Before every final `tfy apply`, show: - Plain-English summary of the change. - Target tenant and workspace/scope. - Full YAML or diff. - Exact command to be run. -Then ask for explicit confirmation. +Then ask for explicit confirmation. Run only dry-runs before confirmation. ## List MCP Servers -Use the platform UI when available. For API fallback: +Prefer the dashboard when the user is working in the UI. For API fallback: ```bash TFY_API_SH=~/.claude/skills/truefoundry-mcp-servers/scripts/tfy-api.sh $TFY_API_SH GET /api/svc/v1/mcp-servers ``` -Present: +Present servers as: ```text MCP Servers -| Name | Type | Transport | ID | URL | +| Name | Type | Auth | ID | URL / Source | ``` -## Add Remote MCP Server - -Use this for an already deployed MCP-compatible HTTP endpoint. - -Required inputs: - -- Name -- URL -- Transport: `streamable-http` or `sse` -- Auth mode: `header`, `oauth2`, or `passthrough` -- Collaborators, if any - -Manifest: - -```yaml -name: my-remote-server -type: mcp-server/remote -description: Production analytics MCP server -url: https://analytics.example.com/mcp -transport: streamable-http -auth_data: - type: header - headers: - Authorization: "Bearer tfy-secret://tenant:mcp-secrets:api-token" -collaborators: - - subject: team:platform - role_id: viewer -``` +## Connect Remote MCP Server -## Add Virtual MCP Server - -Use this to expose selected tools from multiple existing MCP servers through one server. - -Manifest: - -```yaml -name: dev-tools -type: mcp-server/virtual -description: Composite server for development workflows -servers: - - name: code-analysis-server - enabled_tools: - - lint - - analyze - - name: deployment-server - enabled_tools: - - deploy -collaborators: - - subject: team:platform - role_id: viewer -``` +Use this for an existing HTTP MCP endpoint. -## Add OpenAPI MCP Server +Collect: -Use this to expose an OpenAPI spec as MCP tools. Remote spec URLs must be confirmed by the user as trusted before use. +- `name` +- `description` +- `url` +- collaborators and roles +- auth enabled or disabled +- if auth is enabled: API key/header, OAuth2, or token passthrough -Manifest: +Auth rules: -```yaml -name: internal-api -type: mcp-server/openapi -description: Internal API exposed as MCP tools -spec: - type: remote - url: https://internal.example.com/openapi.json -collaborators: - - subject: team:platform - role_id: viewer -``` +- No auth: omit `auth_data`. +- API key/header auth: support shared credentials and individual credentials; require at least one header. +- OAuth2: support authorization code and client credentials; include optional scopes, PKCE/code challenge methods, Dynamic Client Registration URL, and additional token params only when supplied or shown by the UI preview. +- Token passthrough: use the caller's existing TrueFoundry token; no extra fields are needed. -For sensitive APIs, prefer inline specs: - -```yaml -spec: - type: inline - content: | - openapi: "3.0.0" - info: - title: Internal API - version: "1.0" - paths: {} -``` +Use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) for concrete YAML shapes. + +## Connect Official Remote MCP Server + +Use this for catalog servers such as GitHub, Linear, Sentry, Atlassian, Figma, Slack, Notion, Stripe, HuggingFace, or similar. + +Flow: + +1. Identify the official server in the gateway catalog. +2. Confirm the catalog auth mode. +3. For OAuth2, tell the user they may need to complete a browser authentication flow after creation. +4. For header auth, collect header names and use secret references or per-user placeholders. +5. Confirm collaborators. +6. Generate YAML from the UI preview or the YAML reference. +7. Dry-run, show diff, then apply only after confirmation. + +## Create Virtual MCP Server + +Use this to expose selected tools from multiple existing MCP servers through one virtual MCP server. + +Collect: + +- virtual MCP `name` +- `description` +- source MCP servers +- tools to expose from each source server +- collaborators and roles +- optional source-server auth header override if the gateway requires it + +Flow: + +1. List registered MCP servers. +2. Select source MCP servers. +3. Enumerate available tools for each source server. +4. Ask which tools to expose from each source. +5. Use `servers[].enabled_tools` for selected subsets. +6. Omit `enabled_tools` for a source only when exposing every tool from that source. +7. Add collaborators with `mcp-server-manager` unless requested otherwise. +8. Show virtual server name, source servers, selected tools, and access. +9. Show YAML, dry-run, and apply only after confirmation. + +Use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) for virtual server YAML examples. + +## Create Hosted STDIO MCP Server + +Use this when the user has a local-style MCP config and wants the gateway to host/expose it. + +Collect JSON containing an `mcpServers` object with server `command`, `args`, and optional `env`. + +Flow: + +1. Ask for the STDIO JSON or file. +2. Replace raw environment secrets with secret references where supported, or tell the user which values must be moved to secrets. +3. Use the gateway import flow or YAML preview as the source of truth for the manifest generated after import. +4. Show summary, YAML/diff, dry-run, and confirmation-gated apply. + +Use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) for the input shape. -## Hosted Stdio MCP Server +## Import From OpenAPI Spec -Stdio MCP servers cannot be registered directly. First expose them over HTTP using `mcp-proxy` or an equivalent wrapper, deploy that HTTP service, then register it as `mcp-server/remote`. +Use this to expose OpenAPI operations as MCP tools. -## Edit Existing MCP Server +Collect: + +- `name` +- `description` +- OpenAPI spec source: trusted remote URL or pasted inline spec +- selected tools/operations +- collaborators +- optional auth using the same modes as remote MCP servers + +For remote specs, confirm the URL is trusted before use. Prefer pasted/inline specs for sensitive private APIs. + +## Enable Or Disable Tools + +Tool filtering is supported for normal remote/OpenAPI servers and virtual MCP servers. + +For normal remote/OpenAPI servers: + +1. Fetch the current MCP server config by ID. +2. Inspect the API response or UI YAML preview for the existing tool-selection shape. +3. Fetch or confirm available tool names. +4. Modify only the requested tool-selection fields. +5. Preserve name, URL/spec, auth, collaborators, TLS, tags, and unrelated settings. +6. Show the before/after tool list or YAML diff. +7. Dry-run and apply only after confirmation. + +Do not invent field names for normal-server tool filtering. If the API response does not expose the shape, use the dashboard edit screen or ask the user for the `Apply using YAML` output. + +For virtual servers, use `servers[].enabled_tools`; omit it only when exposing every tool from that source. + +## Update Auth Use update-by-manifest: 1. Fetch the current MCP server config. -2. Convert it into the corresponding manifest shape. -3. Modify only the requested fields. -4. Preserve collaborators, auth settings, and existing server/tool lists unless the user asked to change them. -5. Show the diff and get confirmation. -6. Apply the full updated manifest. +2. Preserve name, URL/spec, selected tools, collaborators, TLS, tags, and unrelated settings. +3. Replace only the requested `auth_data` block. +4. Use secret references for shared credentials. +5. Show old auth mode and new auth mode. +6. Show YAML/diff, dry-run, and apply only after confirmation. + +Use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) for auth examples. -Do not patch blindly from memory. +## Access Control + +Adding collaborators is allowed with confirmation. Removing collaborators is dashboard-only. + +To list access: + +```bash +$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=mcp-server&resourceId=RESOURCE_ID' +``` + +When changing access, show the before/after collaborator list and preserve unrelated server config. + +## Add To Client + +The gateway UI can generate setup snippets for Cursor, VS Code, Claude Code, Python, TypeScript, Windsurf, and Codex. + +Use the dashboard `Add to Client` modal or the generated snippet. Do not click, reveal, paste, or print API keys unless the user explicitly asks and understands the exposure. ## Apply +Always run the dry-run first: + ```bash tfy apply -f mcp-server.yaml --dry-run --show-diff -tfy apply -f mcp-server.yaml ``` -Run the final apply only after explicit user confirmation. +Run the final apply only after explicit user confirmation: + +```bash +tfy apply -f mcp-server.yaml +``` ## Delete @@ -183,10 +245,13 @@ To delete this MCP server, open the TrueFoundry dashboard, go to AI Gateway -> M - The user can list MCP servers. -- The user can add remote, virtual, OpenAPI, or hosted stdio-backed MCP servers. -- The user can update an existing MCP server through a reviewed full-manifest apply. -- Secrets are referenced with `tfy-secret://...`, never embedded. -- Final `tfy apply` is gated by a summary, YAML/diff, exact command, and explicit confirmation. -- Deletes are dashboard-only. +- The user can create remote, official remote, virtual, OpenAPI, and hosted STDIO-backed MCP servers. +- Auth-disabled, API key, OAuth2, and token-passthrough configurations match the live gateway YAML shape. +- Tool enable/disable updates preserve unrelated server config. +- Auth and access changes use reviewed full-manifest updates. +- Client attachment guidance covers Cursor, VS Code, Claude Code, Python, TypeScript, Windsurf, and Codex. +- Shared credentials use `tfy-secret://...` references or explicit placeholders. +- Final `tfy apply` is gated by summary, YAML/diff, exact command, and explicit confirmation. +- Deletes and collaborator removals are dashboard-only. diff --git a/skills/mcp-servers/references/mcp-gateway-ui-flows.md b/skills/mcp-servers/references/mcp-gateway-ui-flows.md new file mode 100644 index 0000000..46164c9 --- /dev/null +++ b/skills/mcp-servers/references/mcp-gateway-ui-flows.md @@ -0,0 +1,200 @@ +--- +description: UI navigation notes for TrueFoundry MCP Gateway server creation, editing, client attachment, and access control. +--- + +# MCP Gateway UI Flows + +Use this reference when operating or documenting the MCP Gateway dashboard. It captures observed UI paths from `AI Gateway -> MCP Gateway`. + +## Contents + +- Server List +- Add Server Chooser +- Connect Any Remote MCP Server +- Remote MCP Auth Controls +- Create Virtual MCP Server +- Create Hosted STDIO MCP Server +- Import From OpenAPI Spec +- Add To Client + +## Server List + +The MCP Gateway page shows server cards with: + +- server name +- description +- type, such as `Remote` or `Virtual` +- auth mode, such as `No Auth`, `OAuth2`, `Header Auth`, or `Chained` +- primary action, such as `Add to Client` or `Authenticate` + +The small action button on each card opens: + +- `Edit` +- `Access Control` +- `Delete` + +Do not use `Delete` from an agent. Delete remains dashboard-only manual work. + +## Add Server Chooser + +Click `Add Server` to open `Add new MCP Server`. + +Observed creation options: + +- `Connect Official Remote MCP Servers` +- `Connect any Remote MCP Server` +- `Create a Virtual MCP Server` +- `Create a Hosted STDIO-based MCP Server` +- `Import from OpenAPI Spec` + +## Connect Any Remote MCP Server + +Path: `Add Server` -> `Connect any Remote MCP Server`. + +Base fields: + +- `Name` +- `Description` +- `URL` +- `Collaborators` +- optional `Auth Data` +- `Show advanced fields` +- `Apply using YAML` +- `Add MCP Server` + +Default collaborator observed: + +- subject: current user +- displayed role: `MCP Server Manager` +- YAML role id: `mcp-server-manager` + +Use `Apply using YAML` to inspect the manifest before creating or updating. Do not click `Add MCP Server` until the user has explicitly approved the final apply/create action. + +## Remote MCP Auth Controls + +`Auth Data` is optional. Toggle it on to choose: + +- `API Key` +- `OAuth2` +- `Token Passthrough` + +### API Key + +API key mode is for static headers. + +Configuration options: + +- `Shared Credentials`: one key used by everyone. +- `Individual Credentials`: each user provides their own key. +- `Headers`: one or more header key/value pairs. + +For shared credentials, prefer `tfy-secret://...` references. For individual credentials, use placeholders such as `Bearer {{API_KEY}}`. + +### OAuth2 + +OAuth2 mode is for temporary access tokens from a third-party login or server-to-server auth. + +Grant types: + +- `Authorization Code`: user-facing sign-in flow. +- `Client Credentials`: server-to-server flow with shared client credentials. + +Authorization Code fields observed: + +- `Authorization URL` +- `Token URL` +- `Client ID` +- `Client Secret` +- `Registration URL (Used for Dynamic Client Registration)` +- `Code Challenge Methods Supported` +- `JWT Source` +- `Scopes` +- `Additional Token Parameters` + +Client Credentials fields observed: + +- `Token URL` +- `Client ID` +- `Client Secret` +- `JWT Source` +- `Scopes` +- `Additional Token Parameters` + +### Token Passthrough + +Token passthrough forwards the user's existing TrueFoundry auth token to the MCP server. No extra fields were shown. + +## Create Virtual MCP Server + +Path: `Add Server` -> `Create a Virtual MCP Server`. + +Fields: + +- `Name` +- `Description` +- `Collaborators` +- `Source MCP Servers` +- optional `Override authentication header` +- `Selected Tools` +- `Show advanced fields` +- `Apply using YAML` +- `Create Virtual MCP` + +Observed behavior: + +- Source servers can be selected from existing MCP servers. +- Tools can be selected from each source server. +- Edit screen can show available tools and `Enable All Tools`. +- Use `servers[].enabled_tools` in YAML for selected subsets. +- Omit `enabled_tools` only when exposing every tool from that source server. + +## Create Hosted STDIO MCP Server + +Path: `Add Server` -> `Create a Hosted STDIO-based MCP Server`. + +Fields: + +- `STDIO Configuration (JSON)` +- `Upload JSON file` +- `Import Manifest` + +Input is a local-style `mcpServers` JSON object with `command`, `args`, and optional `env`. + +Move real environment credentials to secret references or ask the user to manage them securely; do not preserve raw secrets in chat. + +## Import From OpenAPI Spec + +Path: `Add Server` -> `Import from OpenAPI Spec`. + +Fields observed: + +- `Import OpenAPI Spec` +- `Build via URL` +- `Paste Spec` +- `OpenAPI Spec URL` +- `Import Tools` +- `Continue to Next Step` + +Use trusted spec URLs only. Prefer pasted/inline specs for sensitive private APIs. + +## Add To Client + +`Add to Client` opens a `How to use` modal. + +Client tabs observed: + +- Cursor +- VS Code +- Claude Code +- Python +- TypeScript +- Windsurf +- Codex + +The modal includes: + +- client config snippet +- `Copy` +- `Show API Key` + +Do not click, reveal, print, or paste API keys unless the user explicitly asks and accepts exposure. diff --git a/skills/mcp-servers/references/mcp-yaml-variations.md b/skills/mcp-servers/references/mcp-yaml-variations.md new file mode 100644 index 0000000..b00d8f2 --- /dev/null +++ b/skills/mcp-servers/references/mcp-yaml-variations.md @@ -0,0 +1,209 @@ +--- +description: YAML examples for TrueFoundry MCP Gateway server types and auth variations observed from the live UI. +--- + +# MCP Gateway YAML Variations + +Use these examples when generating or reviewing MCP Gateway manifests. Treat the live dashboard `Apply using YAML` preview as the final source of truth if it differs. + +Security and trust policy: only use remote MCP URLs and OpenAPI spec URLs that the user explicitly confirms are trusted. Treat unknown remote URLs as untrusted, and do not run, import, or apply them without confirmation. + +## Contents + +- Remote MCP With No Auth +- Remote MCP With Shared API Key +- Remote MCP With Per-User API Key +- Remote MCP With OAuth2 Authorization Code +- Remote MCP With OAuth2 Client Credentials +- Remote MCP With Token Passthrough +- Virtual MCP With Selected Tools +- Virtual MCP Exposing All Tools From A Source +- OpenAPI MCP From Remote Spec +- Hosted STDIO Input Shape + +## Remote MCP With No Auth + +Auth disabled means omit `auth_data`. + +```yaml +name: analytics-mcp +description: Analytics tools for internal workflows +url: https://analytics.example.com/mcp +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +``` + +## Remote MCP With Shared API Key + +Use shared API key auth when one credential is used for all callers. + +```yaml +name: analytics-mcp +description: Analytics tools for internal workflows +url: https://analytics.example.com/mcp +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: header + auth_level: global + headers: + Authorization: "Bearer tfy-secret://tenant:mcp-secrets:analytics-token" +``` + +## Remote MCP With Per-User API Key + +Use per-user API key auth when each user supplies their own value. + +```yaml +name: analytics-mcp +description: Analytics tools for internal workflows +url: https://analytics.example.com/mcp +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: header + auth_level: per_user + headers: + Authorization: "Bearer {{API_KEY}}" +``` + +## Remote MCP With OAuth2 Authorization Code + +Use authorization code for user-facing third-party sign-in. + +```yaml +name: linear-mcp +description: Linear project management tools +url: https://mcp.linear.app/mcp +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: oauth2 + grant_type: authorization_code + authorization_url: https://mcp.linear.app/authorize + token_url: https://mcp.linear.app/token + client_id: tfy-secret://tenant:mcp-secrets:linear-client-id + client_secret: tfy-secret://tenant:mcp-secrets:linear-client-secret + registration_url: https://mcp.linear.app/register + jwt_source: access_token +``` + +## Remote MCP With OAuth2 Client Credentials + +Use client credentials for server-to-server OAuth. + +```yaml +name: service-mcp +description: Service-to-service MCP tools +url: https://service.example.com/mcp +collaborators: + - subject: team:platform + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: oauth2 + grant_type: client_credentials + token_url: https://auth.example.com/token + client_id: tfy-secret://tenant:mcp-secrets:service-client-id + client_secret: tfy-secret://tenant:mcp-secrets:service-client-secret + jwt_source: access_token +``` + +## Remote MCP With Token Passthrough + +Use passthrough when the downstream MCP server should receive the caller's existing TrueFoundry auth token. + +```yaml +name: passthrough-mcp +description: MCP server using caller identity +url: https://service.example.com/mcp +collaborators: + - subject: team:platform + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: passthrough +``` + +## Virtual MCP With Selected Tools + +Use `enabled_tools` to expose a subset from each source server. + +```yaml +name: dev-tools +description: Composite server for engineering workflows +type: mcp-server/virtual +servers: + - name: linear + enabled_tools: + - list_issues + - create_issue + - name: deepwiki + enabled_tools: + - read_wiki_structure + - read_wiki_contents +collaborators: + - subject: team:platform + role_id: mcp-server-manager +``` + +## Virtual MCP Exposing All Tools From A Source + +Omit `enabled_tools` only for sources where every tool should be exposed. + +```yaml +name: broad-dev-tools +description: Composite server exposing all DeepWiki tools and selected Linear tools +type: mcp-server/virtual +servers: + - name: deepwiki + - name: linear + enabled_tools: + - list_issues + - create_issue +collaborators: + - subject: team:platform + role_id: mcp-server-manager +``` + +## OpenAPI MCP From Remote Spec + +```yaml +name: internal-api +description: Internal API exposed as MCP tools +type: mcp-server/openapi +spec: + type: remote + url: https://internal.example.com/openapi.json +collaborators: + - subject: team:platform + role_id: mcp-server-manager +``` + +## Hosted STDIO Input Shape + +Hosted STDIO creation starts from an `mcpServers` JSON config. Use the gateway YAML preview as the manifest source after import. + +```json +{ + "mcpServers": { + "exa-user1": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"], + "env": { + "EXA_API_KEY": "REPLACE_WITH_EXA_API_KEY" + } + } + } +} +``` + +Do not leave real env secrets in the JSON when sharing it in chat or committing examples. diff --git a/skills/onboard/install.md b/skills/onboard/install.md index 7ad46c9..ff31f1a 100644 --- a/skills/onboard/install.md +++ b/skills/onboard/install.md @@ -3,13 +3,13 @@ Install just the onboarding skill: ```bash -npx skills add truefoundry/skills -s onboard +npx skills add truefoundry/skills --skill onboard --yes ``` Or install all TrueFoundry skills: ```bash -npx skills add truefoundry/skills --all +npx skills add truefoundry/skills --skill '*' --yes ``` After install, tell your agent: