# Serve7 MCP Connector Library

Reusable [MCP](https://modelcontextprotocol.io) tools for Amazon Connect AI
Agents and Bedrock AgentCore. Seven generic connectors — customer lookup,
create a support ticket, check ticket status, schedule an appointment, update
a CRM record, retrieve knowledge, and create a task — built once here, then
reused across every Serve7 customer engagement instead of being wired up
from scratch per project.

This is project #6 from the Fall 2026 co-op idea list ("Serve7 MCP Connector
Library"). It's a **working first version**: every connector runs end to end
today against an in-memory mock backend (no AWS account, no live CRM, no
credentials needed to try it), with a clean seam for swapping in a real
backend later.

## Why an adapter, not a direct integration

Every connector's business logic (schema validation, what counts as an
error, what fields go in and out) lives in `src/connectors/*.ts` and never
talks to a concrete backend SDK directly. Instead it calls one of five small
interfaces in `src/adapters/types.ts` — `CrmAdapter`, `TicketingAdapter`,
`SchedulingAdapter`, `KnowledgeAdapter`, `TaskAdapter`. Today those are all
implemented in-memory (`src/adapters/mock.ts`). Tomorrow, connecting a real
Salesforce/ServiceNow/Connect-Cases/Bedrock-Knowledge-Base backend means
writing one new adapter class and flipping one switch statement
(`src/adapters/index.ts`) — zero changes to the connector code, its tests, or
the MCP tool definitions an agent sees. See `docs/adding-a-real-adapter.md`.

```
MCP client (Claude Desktop, Bedrock AgentCore, ...)
        │  tool call: customer_lookup({ customerId: "cust-1001" })
        ▼
src/server.ts (stdio) or src/http-server.ts (deployed)
        │  registers every connector as an MCP tool
        ▼
src/connectors/customer-lookup.ts
        │  validates input (zod), calls adapters.crm.lookupCustomer(...)
        ▼
src/adapters/index.ts  →  mock.ts today, a real adapter later
```

## Project layout

```
src/
  connectors/       one file per MCP tool — schema + business logic only
  adapters/          the CRM/ticketing/scheduling/knowledge/task interfaces,
                      plus the in-memory mock implementations
  mock-data/         seed data the mock adapters serve
  mcp-server-factory.ts   registers every connector on an McpServer instance
  server.ts          stdio entrypoint (local dev, Claude Desktop, Claude Code)
  http-server.ts      Streamable-HTTP entrypoint (deployed, e.g. behind Lambda)
tests/               one test file per connector + a registry sanity test
deploy/              Dockerfile + AWS SAM template for a Lambda deployment
docs/                per-connector reference + how to add a real adapter
```

## Running it locally

```bash
npm install
npm test              # 29 tests, all against the mock adapters
npm run typecheck      # strict TypeScript, zero `any` in connector code
npm start              # stdio MCP server — Ctrl+C to stop
npm run start:http      # HTTP MCP server on :8080 (curl http://localhost:8080/health)
npm run smoke           # real MCP client over stdio, calls all 7 tools end to end
npm run smoke:http      # same, over HTTP — start:http must be running first
```

### Wiring it into Claude Desktop / Claude Code

Point an MCP client at the stdio server, e.g. in Claude Desktop's
`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "serve7-connectors": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/serve7-mcp-connectors/src/server.ts"]
    }
  }
}
```

Then ask it something like "look up customer cust-1001" or "what knowledge
articles do we have on emergency close announcements?" — it'll call
`customer_lookup` / `retrieve_knowledge` against the mock data.

## Deploying it for real use (e.g. from Bedrock AgentCore)

See `deploy/README.md` — builds a container-image Lambda behind an
IAM-authenticated Function URL via `sam deploy`.

## Adding an 8th connector

1. Create `src/connectors/my-new-tool.ts` using `defineConnector()` — copy
   the shape of an existing one, e.g. `create-task.ts`.
2. Add it to the `CONNECTORS` array in `src/connectors/index.ts`.
3. Add a test file in `tests/`.
4. Document it in `docs/connectors.md`.

`server.ts`, `http-server.ts`, and the registry test all pick it up
automatically — nothing else to touch.

## What's deliberately out of scope for this first version

Per the original project brief, each connector should eventually also cover
authentication approach (done, at the adapter layer), a deployment template
(done, `deploy/`), and documentation (done, `docs/`) — all shipped. Not yet
built, and worth a fast-follow: a real adapter for at least one backend (so
this stops being all-mock), and wiring a live Bedrock AgentCore agent to call
it over the deployed HTTP endpoint end to end.