Metadata-Version: 2.4
Name: localcore-gateway
Version: 0.3.0
Summary: Local, faithful-enough reimplementation of AWS Bedrock AgentCore Gateway, with a pluggable local Lambda backend.
Project-URL: Homepage, https://github.com/tawAsh1/localcore-gateway
Project-URL: Repository, https://github.com/tawAsh1/localcore-gateway
Project-URL: Issues, https://github.com/tawAsh1/localcore-gateway/issues
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agentcore,agents,aws,bedrock,emulator,gateway,lambda,local,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: fastmcp<3.3,>=3.2
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == 'aws'
Description-Content-Type: text/markdown

# localcore-gateway

[![PyPI](https://img.shields.io/pypi/v/localcore-gateway.svg)](https://pypi.org/project/localcore-gateway/)
[![CI](https://github.com/tawAsh1/localcore-gateway/actions/workflows/ci.yml/badge.svg)](https://github.com/tawAsh1/localcore-gateway/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python ≥3.11](https://img.shields.io/badge/python-%E2%89%A53.11-blue.svg)](pyproject.toml)

English | [日本語](README.ja.md)

A local, faithful-enough reimplementation of **AWS Bedrock AgentCore Gateway**,
with a pluggable **local Lambda backend**. Develop and test agent ↔ gateway ↔
Lambda integrations entirely on your machine, then point the same MCP client at
the real AWS gateway with no code changes.

There is no official local emulator for AgentCore Gateway (AWS's `agentcore dev`
is for the *Runtime*, not the Gateway). This fills that gap.

> **0.x — unstable.** The CLI flags and config schema may change between
> minor releases until 1.0. Pin a version if you depend on it.

## What it reproduces

- **MCP Streamable-HTTP at `/mcp`** — the same wire surface as the real gateway
  (built on the [FastMCP](https://github.com/jlowin/fastmcp) 3.x server; no
  hand-rolled JSON-RPC), including the modern (May 2026+) behavior:
  **stateful sessions** (`Mcp-Session-Id`) and **SSE-streamed responses**.
  ⚠️ This is the new default — `server: { stateless: true }` restores the
  previous buffered-JSON mode.
- **Interactive passthrough (MCP targets)** — mid-call **progress** and
  **logging** notifications stream through to the caller as they're
  produced, and downstream **elicitation** (form mode) and **sampling**
  requests are relayed to your client and answered back down — the same
  passthroughs the real gateway documents.
- **Target aggregation** — every `(target, tool)` is exposed as one MCP tool
  named `target___tool` (AgentCore's triple-underscore convention).
- **AgentCore Lambda contract** — the tool arguments are passed as the Lambda
  **event**; the tool identity is delivered via
  `context.client_context.custom['bedrockAgentCoreToolName']`; the Lambda's
  return value becomes the tool result.
- **OpenAPI targets** — a REST API's spec becomes MCP tools; the tool name is
  the operation's `operationId` **verbatim** (as the real gateway does, not a
  slugified form), spec-level security is ignored (auth configured out of
  band).
- **Smithy targets** — a Smithy 2.0 JSON AST model's operations become MCP
  tools (`aws.protocols#restJson1` only and 10 MB max, same as the real
  gateway); tool name = the operation's shape name; restJson1 HTTP bindings
  (`httpLabel`/`httpQuery`/`httpHeader`/`httpPayload`) drive the request;
  auth is none/apikey/bearer for local servers or SigV4 for real AWS
  services. This completes the real gateway's target-type matrix.
- **MCP-passthrough targets** — another MCP server's whole catalog is
  proxied: tools, **prompts** (`target___prompt`, AWS's documented naming),
  and **resources** (URIs as-is; shared URIs routed by `resource_priority`,
  the AgentCore `resourcePriority` analog), with `prompts/get` and
  `resources/read` forwarded live. Streamable HTTP is the AgentCore-faithful
  mode; a local stdio `command` mode is also available as a local-only
  convenience (no AWS analog).
- **Target re-sync** — `lcgw sync` is the `SynchronizeGatewayTargets` analog:
  MCP targets re-discover their upstream catalog on a running gateway, no
  restart (synchronous, unlike AWS's async 202-style API). Plus a dev-loop
  extra with no AWS analog: `lcgw tail` streams every tool invocation live.

```yaml
targets:
  - type: mcp
    name: mytools
    url: http://127.0.0.1:9000/mcp
    auth: { type: bearer, value: "${TOKEN}" }   # expanded from the environment
```

## Hybrid debugging (mix in real AWS)

With the `aws` extra installed, the local gateway can mix **real AWS
resources** in next to local ones — iterate on one tool locally while the
rest of your production toolset stays real:

- **`type: aws-gateway`** — proxy a **deployed AgentCore Gateway**: its tools
  pass through with their `remoteTarget___tool` names **verbatim**
  (unprefixed); auth is bearer (OAuth/JWT) or SigV4 (IAM). No AWS analog —
  purely a hybrid-workflow tool.
- **`lambda.backend: aws`** — a third Lambda backend: the tool schema is
  local, the handler is the **real deployed function** (same AgentCore
  ClientContext contract, CloudWatch log tail included; retries disabled so
  a side-effecting invoke is never silently doubled).

See [`examples/hybrid_config.yaml`](examples/hybrid_config.yaml) and the
[configuration reference](docs/configuration.md).

## Testing & contracts (local-only extras)

- **Mock targets** (`type: mock`) — tools declared entirely in config with
  canned responses/errors, so the agent can be developed before the tools
  exist. No AWS analog.
- **Contract checks** (`server.contract_checks: warn|error`) — validate tool
  arguments and results against the declared JSON Schemas at the gateway,
  catching schema/handler drift before deploying. Off by default (the real
  gateway doesn't validate).
- **`localcore_gateway.testing`** — public pytest helpers: `serve_gateway`
  spins up the full gateway on an ephemeral port, `call_tool` makes one-shot
  assertions. See [Testing your handlers](docs/testing.md).
- **Config validation** — `lcgw schema` emits the config file's JSON Schema
  (wire it to your editor via yaml-language-server); `lcgw preflight` checks
  a config against real-AgentCore deploy constraints (name patterns, quotas,
  local-only constructs) before you deploy. See the
  [CLI reference](docs/cli.md).

## Local Lambda backends

| backend  | Docker | fidelity | use it for |
|----------|--------|----------|------------|
| `native` | no     | **one subprocess per target** (real process isolation — monorepo-safe), faithful `event`/`context`, error envelope, CloudWatch-style logs, **hot reload**, **hard timeout** | the fast dev loop |
| `sam`    | yes    | the **real** AWS Lambda Linux runtime via `sam local start-lambda` | full Linux-runtime fidelity check before AWS |
| `aws`    | no     | the **real deployed function** (requires the `aws` extra + credentials) | hybrid debugging against production-like resources |

## Documentation

- [Architecture](docs/architecture.md) — request flow, AgentCore contract mapping, component map
- [Configuration reference](docs/configuration.md) — every config field
- [Writing Lambda handlers](docs/lambda-handlers.md) — the handler contract, multi-tool, errors, logs, native vs sam
- [Testing your handlers](docs/testing.md) — `localcore_gateway.testing`, mock targets, contract checks in pytest
- [CLI reference](docs/cli.md) — `serve` / `dev` / `tools` / `invoke` / `sync` / `tail` / `schema` / `preflight`
- [Connecting agents](docs/connecting-agents.md) — point an MCP client at it; promote to real AWS

## Install

```bash
uv tool install localcore-gateway      # or: pipx install localcore-gateway
uvx --from localcore-gateway lcgw --help   # one-off, no install
```

For the real-AWS passthrough features (`type: aws-gateway`,
`lambda.backend: aws`), install the `aws` extra:

```bash
uv tool install 'localcore-gateway[aws]'   # or: pip install 'localcore-gateway[aws]'
```

## Quick start

A handler and a config (nothing else needed):

```python
# handlers.py
def handler(event, context):
    return {"sum": event["a"] + event["b"]}
```

```yaml
# gateway.yaml
targets:
  - type: lambda
    name: demo
    lambda: { backend: native, handler: handlers.handler }
    tools:
      - name: add
        inputSchema:
          type: object
          properties: { a: { type: number }, b: { type: number } }
          required: [a, b]
```

```bash
lcgw tools  -c gateway.yaml
lcgw invoke -c gateway.yaml demo___add --data '{"a":2,"b":40}'
lcgw serve  -c gateway.yaml            # MCP at http://127.0.0.1:8080/mcp
lcgw dev    -c gateway.yaml            # same, with hot reload
lcgw tail   -c gateway.yaml            # live per-invocation stream (running gateway)
lcgw sync   -c gateway.yaml            # re-sync MCP targets (running gateway)
```

Point any MCP client at `http://127.0.0.1:8080/mcp`. Richer examples (multi
target, `math_handlers.py`, Strands agent, MCP-passthrough via
`mcp_config.yaml`) are in [`examples/`](examples/).

### From source (development)

```bash
git clone https://github.com/tawAsh1/localcore-gateway && cd localcore-gateway
uv sync
uv run pytest
uv run lcgw serve -c examples/config.yaml
```

### Using the `sam` backend

Run `sam local start-lambda` in your SAM project, then set in the target:

```yaml
lambda:
  backend: sam
  sam_endpoint: http://127.0.0.1:3001
  sam_function: DemoFunction
```

## Configuration

See [`examples/config.yaml`](examples/config.yaml). A target declares a Lambda
(`backend`, `handler`/`sam_function`, `memory_mb`, `timeout_sec`, `env`) and the
tools it backs (each with an explicit JSON Schema). One Lambda can back many
tools; the handler branches on `bedrockAgentCoreToolName`.

## Known limitations

- `native` runs your handler in a subprocess but is **not a security
  sandbox** (no filesystem/network jail) — only point it at trusted code.
- `native` serializes invokes per target (one warm execution environment);
  it does not model Lambda's concurrent-environment scaling.
- `sam` per-invoke logs appear in the `sam local` console (out-of-band for the
  Invoke API).
- AgentCore's builtin semantic tool search (`x_amz_bedrock_agentcore_search`)
  is **not implemented** (intentionally omitted).
- All four real target types are implemented — **Lambda**, **OpenAPI**,
  **Smithy**, and **MCP-passthrough** — plus the local-only **AWS-gateway
  passthrough** and **mock** targets. Outbound auth (OpenAPI and
  MCP-passthrough alike) covers static API key (header/query) and bearer;
  OAuth 2LO is out of scope. Smithy accepts any restJson1 model locally
  (AWS restricts custom models to AWS services) and requires `base_url`
  (endpoint rule sets are not implemented).
- The hybrid features (`type: aws-gateway`, `lambda.backend: aws`) require
  the `aws` extra and real AWS credentials, and are subject to AWS-side
  behavior (cold starts, IAM, quotas) — nothing local emulates them.

## License

[Apache License 2.0](LICENSE). See [`NOTICE`](NOTICE) for attribution and the
trademark disclaimer below.

## Trademarks & disclaimer

This is an unofficial, community project. It is **not affiliated with,
endorsed by, or sponsored by Amazon Web Services, Inc. or its affiliates**.

"AWS", "Amazon Web Services", "Amazon Bedrock", "Amazon Bedrock AgentCore",
and "AWS Lambda" are trademarks of Amazon.com, Inc. or its affiliates. They
are used here only nominatively, to accurately describe the AWS service this
project interoperates with / reimplements locally. No AWS trademark, logo, or
trade dress is used as the name or branding of this project.
