feat!: merge mcp.json into agentcore.json

[notgitika]

Description

Merges the separate mcp.json configuration file into agentcore.json as a breaking change. Gateway and MCP tool definitions are now stored alongside the rest of the project spec in a single file, simplifying configuration management.

CDK PR: https://github.com/aws/agentcore-l3-cdk-constructs/pull/99

Key changes:

• Removed readMcpSpec() / writeMcpSpec() from ConfigIO; all reads/writes go through readProjectSpec() / writeProjectSpec()
• Added agentCoreGateways and mcpRuntimeTools fields to AgentCoreProjectSpecSchema with .default([])
• Added extractMcpSpec() helper for backwards-compatible MCP type extraction
• Removed getMcpConfigPath() from PathResolver
• Updated all primitives, operations, TUI screens, and tests to use the unified spec

Related Issue

Closes #611

Documentation PR

N/A

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[tejaskash]

Code review

Found 4 issues:

1. Wrong return type format: save function uses { ok: boolean; error?: string } instead of the required { success: Boolean, error?: string } format (AGENTS.md says "Wheverever there is a requirement to use something that returns a success result and an error message you must use this format { success: Boolean, error?:string}")

agentcore-cli/src/cli/tui/screens/schema/McpGuidedEditor.tsx

Lines 73 to 76 in 81e3202

	// Wrap save to merge MCP fields back into the full project spec
	const save = async (mcpContent: string): Promise<{ ok: boolean; error?: string }> => {
	if (!projectSpec) return { ok: false, error: 'No project spec loaded' };
	const mcpData = JSON.parse(mcpContent) as AgentCoreMcpSpec;

2. Inline type used instead of existing type: { agentCoreGateways: typeof context.projectSpec.agentCoreGateways } should use Pick<AgentCoreMcpSpec, 'agentCoreGateways'> or similar (AGENTS.md says "Always look for existing types before creating a new type inline.")

agentcore-cli/src/cli/commands/deploy/actions.ts

Lines 84 to 86 in 81e3202

	// Read project spec for gateway information (used later for deploy step name and outputs)
	let mcpSpec: { agentCoreGateways: typeof context.projectSpec.agentCoreGateways } | null = null;
	try {

3. Missing uniqueBy validation on new arrays: agentCoreGateways, mcpRuntimeTools, and unassignedTargets are added without .superRefine(uniqueBy(...)), while every other resource array in the schema (agents, memories, credentials, evaluators, onlineEvalConfigs, policyEngines) has this validation. Duplicate names would pass schema validation but fail at deploy time. This same pattern gap was flagged in PR feat: add policy engine and policy support #579 for policyEngines.

agentcore-cli/src/schema/schemas/agentcore-project.ts

Lines 209 to 215 in 81e3202

	// MCP / Gateway resources (previously in mcp.json)
	agentCoreGateways: z.array(AgentCoreGatewaySchema).default([]),
	mcpRuntimeTools: z.array(AgentCoreMcpRuntimeToolSchema).optional(),
	unassignedTargets: z.array(AgentCoreGatewayTargetSchema).optional(),

4. Loss of strict validation for MCP fields: AgentCoreMcpSpecSchema previously had .strict() to reject unknown fields (with a dedicated test "rejects extra fields"). The fields are now embedded in AgentCoreProjectSpecSchema which is not strict, so typos in MCP field names (e.g. agentCoreGatways) will be silently ignored instead of rejected.

agentcore-cli/src/schema/schemas/agentcore-project.ts

Lines 209 to 215 in 81e3202

	// MCP / Gateway resources (previously in mcp.json)
	agentCoreGateways: z.array(AgentCoreGatewaySchema).default([]),
	mcpRuntimeTools: z.array(AgentCoreMcpRuntimeToolSchema).optional(),
	unassignedTargets: z.array(AgentCoreGatewayTargetSchema).optional(),

[notgitika]

Fixed all 4 in ef28a16:

1. Swapped to SaveDocumentResult type
2. Using Pick<AgentCoreMcpSpec, 'agentCoreGateways'> now
3. Added uniqueBy validation on all three MCP arrays
4. Added .strict() to AgentCoreProjectSpecSchema

[tejaskash]

All 4 review comments addressed. The ok vs success naming in SaveDocumentResult is a pre-existing issue beyond this PR's scope — can be tracked separately.