From 577678a0a8b400f26356468b3e55fe21c89003bf Mon Sep 17 00:00:00 2001 From: faishal Date: Fri, 17 Apr 2026 23:14:24 +0530 Subject: [PATCH] fix(codex): add awsknowledge compatibility MCP configs --- docs/TROUBLESHOOTING.md | 36 +++++++++++++++++++ .../.codex-plugin/plugin.json | 2 +- plugins/databases-on-aws/.mcp.codex.json | 27 ++++++++++++++ .../deploy-on-aws/.codex-plugin/plugin.json | 2 +- plugins/deploy-on-aws/.mcp.codex.json | 35 ++++++++++++++++++ .../.codex-plugin/plugin.json | 2 +- plugins/migration-to-aws/.mcp.codex.json | 28 +++++++++++++++ 7 files changed, 129 insertions(+), 3 deletions(-) create mode 100644 plugins/databases-on-aws/.mcp.codex.json create mode 100644 plugins/deploy-on-aws/.mcp.codex.json create mode 100644 plugins/migration-to-aws/.mcp.codex.json diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 06ca4d2c..8b2aa513 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -212,6 +212,42 @@ Replace `RUN_ID` with the workflow run ID from your pull request's **Checks** ta - **Repository collaborators** (write access) can re-run workflows directly. - **Fork contributors** cannot re-run workflows on the upstream repo. Ask a maintainer to re-run the failed jobs, or push an empty commit (`git commit --allow-empty -m "retry CI"`) to trigger a fresh run. +## Codex + +### MCP Startup Failure: `awsknowledge` + +If Codex reports an `awsknowledge` startup error similar to: + +```text +Transport channel closed, when send initialized notification +``` + +the plugin now uses a Codex-specific MCP configuration that proxies `awsknowledge` through local stdio using `uvx fastmcp run`. + +1. Verify Codex is using the Codex manifest and MCP file for your plugin: + - `.codex-plugin/plugin.json` points to `./.mcp.codex.json` +2. Verify `uvx` is installed and available in `PATH`: + + ```bash + uvx --version + ``` + +3. Restart Codex and retry plugin startup. + +If the issue persists, collect the full startup error and open or comment on: + +- https://github.com/awslabs/agent-plugins/issues/130 + +### Codex Debug Override: direct HTTP transport + +For diagnostics only, you can force the previous direct HTTP transport path: + +1. Edit the plugin's `.codex-plugin/plugin.json` +2. Change `mcpServers` from `./.mcp.codex.json` to `./.mcp.json` +3. Restart Codex + +Use this only for debugging and rollback. The Codex default should remain `./.mcp.codex.json`. + ## Other AI Assistants Support for additional AI assistants will be added here as the plugin system expands. diff --git a/plugins/databases-on-aws/.codex-plugin/plugin.json b/plugins/databases-on-aws/.codex-plugin/plugin.json index 33831529..b4a5b797 100644 --- a/plugins/databases-on-aws/.codex-plugin/plugin.json +++ b/plugins/databases-on-aws/.codex-plugin/plugin.json @@ -26,7 +26,7 @@ "sql" ], "skills": "./skills/", - "mcpServers": "./.mcp.json", + "mcpServers": "./.mcp.codex.json", "interface": { "displayName": "Databases on AWS", "shortDescription": "Design schemas, query data, and choose the right AWS database path.", diff --git a/plugins/databases-on-aws/.mcp.codex.json b/plugins/databases-on-aws/.mcp.codex.json new file mode 100644 index 00000000..ea589104 --- /dev/null +++ b/plugins/databases-on-aws/.mcp.codex.json @@ -0,0 +1,27 @@ +{ + "mcpServers": { + "awsknowledge": { + "args": [ + "fastmcp", + "run", + "https://knowledge-mcp.global.api.aws" + ], + "command": "uvx", + "env": { + "FASTMCP_LOG_LEVEL": "ERROR" + }, + "timeout": 120000, + "type": "stdio" + }, + "aurora-dsql": { + "command": "uvx", + "args": [ + "awslabs.aurora-dsql-mcp-server@latest" + ], + "disabled": true, + "env": { + "FASTMCP_LOG_LEVEL": "ERROR" + } + } + } +} diff --git a/plugins/deploy-on-aws/.codex-plugin/plugin.json b/plugins/deploy-on-aws/.codex-plugin/plugin.json index 1d391615..9bc0e06a 100644 --- a/plugins/deploy-on-aws/.codex-plugin/plugin.json +++ b/plugins/deploy-on-aws/.codex-plugin/plugin.json @@ -22,7 +22,7 @@ "architecture" ], "skills": "./skills/", - "mcpServers": "./.mcp.json", + "mcpServers": "./.mcp.codex.json", "interface": { "displayName": "Deploy on AWS", "shortDescription": "Pick AWS services, estimate cost, and generate infrastructure.", diff --git a/plugins/deploy-on-aws/.mcp.codex.json b/plugins/deploy-on-aws/.mcp.codex.json new file mode 100644 index 00000000..d5f0fac1 --- /dev/null +++ b/plugins/deploy-on-aws/.mcp.codex.json @@ -0,0 +1,35 @@ +{ + "mcpServers": { + "awsiac": { + "args": [ + "awslabs.aws-iac-mcp-server@latest" + ], + "command": "uvx" + }, + "awsknowledge": { + "args": [ + "fastmcp", + "run", + "https://knowledge-mcp.global.api.aws" + ], + "command": "uvx", + "env": { + "FASTMCP_LOG_LEVEL": "ERROR" + }, + "timeout": 120000, + "type": "stdio" + }, + "awspricing": { + "args": [ + "awslabs.aws-pricing-mcp-server@latest" + ], + "command": "uvx", + "disabled": false, + "env": { + "FASTMCP_LOG_LEVEL": "ERROR" + }, + "timeout": 120000, + "type": "stdio" + } + } +} diff --git a/plugins/migration-to-aws/.codex-plugin/plugin.json b/plugins/migration-to-aws/.codex-plugin/plugin.json index 8ee96e5a..cc7460ed 100644 --- a/plugins/migration-to-aws/.codex-plugin/plugin.json +++ b/plugins/migration-to-aws/.codex-plugin/plugin.json @@ -20,7 +20,7 @@ "fargate" ], "skills": "./skills/", - "mcpServers": "./.mcp.json", + "mcpServers": "./.mcp.codex.json", "interface": { "displayName": "Migration to AWS", "shortDescription": "Discover GCP workloads and plan a migration path to AWS.", diff --git a/plugins/migration-to-aws/.mcp.codex.json b/plugins/migration-to-aws/.mcp.codex.json new file mode 100644 index 00000000..9d5fa660 --- /dev/null +++ b/plugins/migration-to-aws/.mcp.codex.json @@ -0,0 +1,28 @@ +{ + "mcpServers": { + "awsknowledge": { + "args": [ + "fastmcp", + "run", + "https://knowledge-mcp.global.api.aws" + ], + "command": "uvx", + "env": { + "FASTMCP_LOG_LEVEL": "ERROR" + }, + "timeout": 120000, + "type": "stdio" + }, + "awspricing": { + "args": [ + "awslabs.aws-pricing-mcp-server@latest" + ], + "command": "uvx", + "env": { + "FASTMCP_LOG_LEVEL": "ERROR" + }, + "timeout": 120000, + "type": "stdio" + } + } +}