Repository map

Repository identity confirmed: this repository IS the MCP server. The executable server, tool implementations, OptiCat HTTP client, protocol entry points, and AWS deployment definitions are all present here; it is not merely a client or host-agent shell. Same-day escalation: N/A — the server does not live elsewhere.

Audit date: 2026-08-07. Repository path: /Users/np/Documents/GitHub/opticat-mcp. The requested template did not exist in the checkout when this pass began, so this file reconstructs the requested structure at the specified path. It contains no unresolved placeholders. The repository itself names the package and infrastructure opticat-mcp; the string opticatmcppoc does not occur in the checked-in source.

1. Language, framework, and MCP SDK

Dependency declarations and SDK currency

There is no lockfile, so the exact MCP version used by any historical deployment cannot be recovered from this repository. The source is written against MCP SDK v1: it imports mcp.server.fastmcp.FastMCP and passes v1-style transport settings to the constructor. As of this audit, PyPI identifies MCP Python SDK 2.0.0 as the current stable release, and its current examples use MCPServer; PyPI explicitly tells v1 consumers to use a <2 upper bound until migration. This repository has no such bound. Therefore:

• exact resolved repository SDK version: N/A — unpinned and no lockfile;
• source API generation: v1-era FastMCP;
• current SDK stable line: 2.0.0;
• currentness: not current;
• reproducibility: not reproducible from manifests alone;
• fresh-install compatibility: the declarations now permit/install v2 even though the source uses v1 API paths.

Other packaging drift:

• Root pyproject.toml omits boto3, although server credential fallbacks import it. Root requirements.txt does include it.
• There is no [project.scripts] entry. README commands using uvx opticat-mcp-server or installing opticat-mcp-server are not implemented by this package metadata.
• README says MIT, but no LICENSE file exists.

2. Transport and server entry points

Canonical FastMCP runtime

Transport findings:

• Streamable HTTP: implemented and always selected by main().
• Stdio: N/A — mentioned by the module docstring and local Kiro setup docs, but no executable branch selects stdio.
• SSE: N/A — no SSE server invocation exists.
• Foundry-native: N/A — no Azure AI Foundry runtime or binding exists.
• WebSocket: N/A — no implementation exists.

deployment/agentcore/agentcore_wrapper.py sets MCP_TRANSPORT=http, but src/opticat_mcp/server.py never reads MCP_TRANSPORT; it still reaches the hard-coded Streamable HTTP call. The README/SETUP Kiro configurations launch the module as a subprocess, which implies stdio, but the process actually starts an HTTP server.

Lambda/API Gateway runtime

Bedrock AgentCore runtime

AgentCore is hosting/runtime metadata around the Python MCP server; it is not the tool implementation framework.

3. Directory map

The table covers every repository/application directory. Internal .git/objects, refs, and other Git implementation subdirectories are intentionally summarized under .git/ because they are not project source.

Agent instructions, system prompts, and prompt-like files

1. /Users/np/Documents/GitHub/opticat-mcp/AGENT_PROMPT.md

   • Explicitly titled “OptiCat Automotive Parts Assistant - System Prompt.”
   • Directs vehicle/tool selection, retailer-brand workflows, chaining, clarification, response formatting, and prohibited behavior.
   • Not loaded by server code; a host must install/use it separately.

2. /Users/np/Documents/GitHub/opticat-mcp/src/opticat_mcp/server.py

   • Tool docstrings include extensive model-facing workflows and usage rules. FastMCP uses those docstrings as tool descriptions, so this prompt-like content is active through tools/list.

3. /Users/np/Documents/GitHub/opticat-mcp/deployment/lambda/lambda_handler.py

   • Contains an independently maintained set of model-facing tool descriptions and JSON schemas.

4. /Users/np/Documents/GitHub/opticat-mcp/deployment/lambda/tool_schema.json

   • Static seven-tool binding schema for an AWS Lambda/AgentCore Gateway target.

5. /Users/np/Documents/GitHub/opticat-mcp/deployment/lambda/COPILOT_STUDIO_SETUP.md

   • Host integration instructions for Copilot Studio and AgentCore Gateway, including committed credential material.

6. /Users/np/Documents/GitHub/opticat-mcp/data/OptiCat_MCP_Proposal_Tenexity.docx

   • Planning material describing an intended LLM “instruction set,” terminology translation, inference, and clarification logic. It is not loaded at runtime.

Repository-level AGENTS.md, CLAUDE.md, or equivalent coding-agent instruction file: N/A — none exists in this repository.

MCP prompt registrations/resources: N/A — no @mcp.prompt(), @mcp.resource(), prompts/list, or resources are implemented.

4. Tool registration

Canonical FastMCP registration

• File: src/opticat_mcp/server.py
• Server creation: module-level mcp = FastMCP(...)
• Pattern: bare decorators on async functions:

@mcp.tool()
async def tool_name(...) -> str:
    ...

• Naming: no decorator overrides; the exact model-visible name is the Python function name.
• Description generation: FastMCP derives the tool description from the function docstring.
• Input generation: FastMCP derives JSON Schema from the signature/type annotations.
• Return type: every tool returns a preformatted string.
• Annotations: none; no readOnlyHint or related MCP annotations are declared.

Registered tools, in source order:

1. search_parts_by_vehicle
2. get_vehicle_years
3. get_vehicle_makes
4. get_vehicle_models
5. get_part_details
6. get_part_applications
7. search_parts
8. get_brand_codes
9. discover_part_types
10. get_vehicles_by_vin
11. get_vehicle_assets
12. get_part_cross_references
13. get_part_supersession
14. check_part_fitment_for_vehicle
15. get_part_attributes
16. get_part_descriptions

No dynamic registry, class-based tool provider, plugin discovery, service container, code generation, or separate controller layer exists.

Lambda registration

deployment/lambda/lambda_handler.py duplicates the surface manually:

• TOOLS maps the same 16 strings to imported functions.
• TOOL_SCHEMAS independently describes the same 16 tools.
• handler() returns TOOL_SCHEMAS.values() for tools/list and dispatches calls through TOOLS.

This schema is shorter than the FastMCP docstrings and can drift independently.

Static AgentCore Gateway registration

deployment/lambda/tool_schema.json exposes only seven older tools:

• search_parts_by_vehicle
• get_vehicle_years
• get_vehicle_makes
• get_vehicle_models
• get_part_details
• get_part_applications
• search_parts

It omits the other nine canonical tools, including VIN decode, cross-reference, supersession, and fitment verification.

5. API client layer and referenced endpoints

Executable client implementation

There is no separate client module. src/opticat_mcp/server.py colocates:

• BASE_URL at line 19;
• get_api_key() at lines 22-49;
• call_opticat_api() at lines 53-68;
• paginated facet helper find_in_facets() at lines 71-93;
• every tool.

call_opticat_api() behavior:

• creates a new httpx.AsyncClient(timeout=30.0) per call;
• sends an HTTPS POST;
• serializes a JSON request body;
• sends headers X-Api-Key and Content-Type: application/json;
• calls raise_for_status();
• parses JSON;
• logs elapsed time.

No connection pool shared across calls, retry/backoff, circuit breaker, cache, response model, database, request persistence, or write-side OptiCat operation exists.

Upstream authentication

Credential resolution order in get_api_key():

1. OPTICAT_API_KEY environment variable.
2. SSM Parameter Store name in OPTICAT_API_KEY_SSM_PARAM, decrypted in AWS_REGION or default eu-central-1.
3. Secrets Manager secret ID opticat-api-key, JSON field OPTICAT_API_KEY, in AWS_REGION or default eu-central-1.

Runtime upstream authentication is exclusively the X-Api-Key header. Reference documentation also describes Basic Auth with API key as username and an api_key query parameter, but executable Python does not use those alternatives.

URL and WSDL references

Upstream operation names

Executable Python uses:

Referenced only in supplied data/manual/Postman material:

The Postman collection contains 22 example POST requests across version, brand-update, vehicle, search, detail, application, and vehicle-asset operations. It uses collection-level Basic Auth. It does not define the implemented VIN operation.

6. Deployment and shipped artifacts

Requested deployment technologies

Automated shipping path: Azure DevOps → AWS CDK

build_pipeline/deploy-pipeline.yaml:

• triggers on main and develop;
• validates pull requests targeting those branches;
• maps main → prod, develop → develop, other source branches → feature;
• uses Python 3.12, Node 22, and AWS CDK CLI 2.178.0;
• runs cdk synth in its Test stage;
• does not run application tests;
• on non-PR success, writes the OptiCat key to SSM SecureString and deploys CDK.

Environment/service-connection mapping:

• region: eu-central-1;
• prod: Azure service connection DS&ML Prod, variable group opticat_mcp_prod;
• develop: DS&ML Dev, variable group opticat_mcp_develop;
• feature: DS&ML Test, variable group opticat_mcp_feature.

The CDK stack creates:

• Lambda opticat-mcp-<env>;
• runtime Python 3.12;
• handler lambda_handler.handler;
• 512 MB memory;
• 29-second timeout;
• environment OPTICAT_API_KEY_SSM_PARAM=/opticat-mcp/<env>/OPTICAT_API_KEY;
• permission to read that SSM SecureString;
• two-week CloudWatch log retention;
• API Gateway REST API opticat-mcp-<env>;
• API Gateway API key and usage plan;
• rate 50 requests/second and burst 100;
• API-key-required root POST and proxy methods.

What the CDK bundle actually ships:

1. dependencies installed from root requirements.txt;
2. src/opticat_mcp/;
3. deployment/lambda/lambda_handler.py.

It excludes data, deployment source, infrastructure source, Markdown, local environments, Git metadata, .env, and several local directories. Therefore the automated Lambda deployment runs the hand-written Lambda MCP adapter, not FastMCP's Streamable HTTP application.

Manual legacy Lambda deployment

deployment/lambda/deploy.sh:

• builds a ZIP from deployment/lambda/requirements.txt;
• copies src/opticat_mcp and lambda_handler.py;
• reads OPTICAT_API_KEY from Secrets Manager opticat-api-key;
• updates an already-existing Lambda named OptiCatMcpProxy;
• sets the key directly in the Lambda environment;
• prints a hard-coded API Gateway /prod/mcp URL and API key.

It does not create the Lambda, API Gateway, or gateway key. Its names and secret model differ from the CDK path.

Bedrock AgentCore direct runtime

deployment/agentcore/.bedrock_agentcore.yaml describes direct code deployment:

• entrypoint deployment/agentcore/agentcore_wrapper.py (stored as an absolute path from the original developer machine);
• Python 3.12, Linux ARM64;
• public network;
• MCP protocol;
• observability enabled;
• AWS JWT enabled;
• short-term AgentCore memory;
• region eu-central-1.

The wrapper loads OPTICAT_API_KEY from Secrets Manager if absent and starts the canonical FastMCP main(). No CI job deploys this configuration; docs prescribe manual agentcore deploy. The runtime ARN in the YAML differs from the ARN in deployment/agentcore/DEPLOYMENT.md.

AgentCore Gateway/Copilot Studio legacy surface

deployment/lambda/tool_schema.json points at a differently named Lambda, OptiCatMcpServer, and exposes a static seven-tool schema. deployment/lambda/COPILOT_STUDIO_SETUP.md documents an AgentCore Gateway and OAuth 2.0 client-credentials connection for Copilot Studio.

Represented AWS identities are not reconciled:

• CDK Lambda: opticat-mcp-<env>;
• manual Lambda: OptiCatMcpProxy;
• gateway-target Lambda: OptiCatMcpServer;
• direct AgentCore runtime: agentcore_server.

Environment variables and secrets

Committed credential material exists in:

• /Users/np/Documents/GitHub/opticat-mcp/deployment/README.md — API Gateway key value;
• /Users/np/Documents/GitHub/opticat-mcp/deployment/lambda/deploy.sh — prints the same key;
• /Users/np/Documents/GitHub/opticat-mcp/deployment/lambda/COPILOT_STUDIO_SETUP.md — OAuth client ID and client secret.

Values are intentionally not reproduced here.

7. Tests

Automated application test suite: N/A — no tests/ directory, pytest/unittest configuration, test dependency, fixtures, mocks, coverage configuration, contract tests, or transport tests exist.

The only test-like file is:

/Users/np/Documents/GitHub/opticat-mcp/deployment/agentcore/test_agentcore_local.py

Intended manual smoke coverage:

1. get vehicle years;
2. get makes for 2007;
3. search brake pads for a 2007 Ford Mustang.

Current executability: broken. It imports agentcore_server and agentcore_server.server, but no agentcore_server.py module or package exists. Current code lives in opticat_mcp.server, and the AgentCore entry is agentcore_wrapper.py.

Pipeline validation:

• Azure stage named Test performs only cdk synth.
• It can validate infrastructure synthesis.
• It does not import the application, list tools, invoke the Lambda handler, test FastMCP transport, verify schemas against functions, or call OptiCat.

No live OptiCat, AWS, or AgentCore calls were made in this discovery pass.

8. Git history

Last 20 commit messages

Only one commit exists, so the requested last 20 contain one row:

What commit messages reveal about known problems: N/A — the sole message is a bulk “initial update” and admits no limitation, timeout, cap, disabled feature, defect, fix, revert, or issue reference.

Commit messages admitting limitations, quoted with hash: N/A — no such commit message exists.

Current-tree limitations cannot be attributed to history because the repository was imported in one commit. Source inspection, not commit narrative, reveals:

• v1 FastMCP source with unbounded requirements that now resolve v2;
• executable HTTP transport versus stdio-oriented local setup docs;
• 16 canonical tools versus a seven-tool static gateway schema;
• multiple unreconciled AWS runtime identities;
• broken manual test imports;
• API result caps and field whitelists inside tool formatters;
• VIN functionality that may be subscription-disabled upstream;
• MCP_TRANSPORT set but ignored;
• prompt/schema drift across FastMCP, Lambda, static gateway, and AGENT_PROMPT.md;
• committed ingress/OAuth credential material.

9. Repository identity and architecture

This is the MCP server repository because it contains all necessary server-side layers:

• MCP server object and entrypoint;
• tool registration and implementation;
• upstream API credential resolution;
• OptiCat request/response logic;
• HTTP/Lambda protocol adapters;
• infrastructure and deployment definitions.

It also contains host instructions and Copilot/Kiro connection docs, but those are ancillary. No external repository is referenced as the location of the actual server implementation.

flowchart LR
    U["User"]
    H["Host agent<br/>Kiro, Copilot Studio, or another MCP host"]

    subgraph S["MCP server components in this repository"]
        F["FastMCP server<br/>16 decorator-registered tools<br/>Streamable HTTP"]
        G["API Gateway REST API<br/>x-api-key ingress"]
        L["Lambda adapter<br/>hand-written JSON-RPC subset<br/>16-tool in-code schema"]
        AG["Bedrock AgentCore runtime or Gateway<br/>direct MCP runtime or legacy 7-tool binding"]
        T["Shared async tool functions<br/>text formatters"]
        C["httpx OptiCat client<br/>credential resolver"]
    end

    subgraph O["OptiCat / TecAlliance references"]
        J["Catalog.jsonEndpoint<br/>executed HTTPS POST target"]
        OPS["Executed operations<br/>VehicleResults, SearchResults,<br/>PartDetails, PartApplications,<br/>VehicleAssets, VehiclesByVIN"]
        SOAP["Catalog SOAP docs and wrapped WSDL<br/>reference only, not executed"]
        ASSET["digital-assets.opticatonline.com<br/>returned URL family, not fetched"]
        TD["TecAlliance SOAP namespace / getSearchResults<br/>reference only, not implemented"]
    end

    U --> H
    H -- "Streamable HTTP" --> F
    H -- "JSON-RPC over HTTPS" --> G
    H -- "OAuth/JWT-managed HTTPS" --> AG
    G --> L
    AG --> F
    AG -. "legacy Gateway target" .-> L
    F --> T
    L --> T
    T --> C
    C -- "X-Api-Key + JSON POST" --> J
    J --> OPS
    OPS --> C
    J -. "response may contain URLs" .-> ASSET
    SOAP -. "documentation only" .-> J
    TD -. "documentation only" .-> J
    C --> T
    T --> H
    H --> U

Executive summary

In plain language, this codebase is the actual Python proof-of-concept MCP server for asking OptiCat automotive-catalog questions: it exposes 16 read-only lookup tools, translates those calls into JSON requests to one OptiCat OnLine endpoint, and formats the results as text for an AI host. Its main implementation is a v1-era FastMCP Streamable HTTP server, while its automated AWS path packages the same tool functions behind a simpler hand-written Lambda adapter and API Gateway; additional AgentCore and Copilot artifacts represent older or parallel deployment approaches. The repository is small and self-contained, but its dependency version is not locked, its docs and deployment surfaces have drifted, its only smoke test is broken, and its one-commit history provides no explanation for those limitations.