Metadata-Version: 2.4
Name: localcore-gateway
Version: 0.2.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: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.30
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)

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).
- **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).

## 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 |

## 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
- [CLI reference](docs/cli.md) — `serve` / `dev` / `tools` / `invoke`
- [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
```

## 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
```

Point any MCP client at `http://127.0.0.1:8080/mcp`. Richer examples (multi
target, `math_handlers.py`, Strands agent) 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).
- Target types: **Lambda** and **OpenAPI** are implemented; MCP-passthrough
  and Smithy are not yet. OpenAPI outbound auth covers static API key
  (header/query) and bearer; OAuth 2LO is out of scope.

## 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.
