Copy page

SDK, CLI and MCP

Command line

The package @lelemon-ai/sdk installs a lelemon command. It has one group, connector, with two commands: validate checks documents against the format and serve answers the four requests of a connector from a file. Both run on your machine. Nothing is sent to Lelemon.

Works in two minutes

Save this fixture as fixture.json. It is a connector with one account.

Code
{
  "manifest": {
    "format": "lelemon-connector/v1",
    "name": "Acme back office",
    "lookup": { "byId": true, "byEmail": true },
    "views": []
  },
  "accounts": [
    {
      "email": "ana@acme.example",
      "object": "account",
      "id": "acc_1",
      "title": "Acme SpA",
      "sections": [
        {
          "title": "Plan",
          "components": [
            { "type": "field", "key": "plan", "label": "Plan", "valueType": "text", "value": "Pro" }
          ]
        }
      ]
    }
  ]
}

In one terminal, serve it. In another, validate what it serves:

Code
npx -y -p @lelemon-ai/sdk lelemon connector serve --fixture fixture.json

npx -y -p @lelemon-ai/sdk lelemon connector validate http://127.0.0.1:4300 --account acc_1

Expected:

Code
Serving fixture.json at http://127.0.0.1:4300 (signatures are not checked)

Code
ok    manifest  http://127.0.0.1:4300/manifest
ok    account  http://127.0.0.1:4300/accounts/acc_1

If you installed the SDK in a project (npm install @lelemon-ai/sdk), run npx lelemon connector ... instead. The format is explained in Connect your back office.

lelemon connector validate

Code
lelemon connector validate <url|file> [--type manifest|account|accountSearch|view]
                                      [--account <id>] [--header "Name: value"]

validate reads a target and checks it with the same validator Lelemon uses on the real answers of your system.

• A URL is a base URL of a connector. The command reads GET {base}/manifest, then GET {base}/views/{id} for each view the manifest declares, and GET {base}/accounts/{id} when you pass --account. Each document gets its own line.
• A file is one JSON document. The command detects its type, or you force it with --type.

Option	Use
<url|file>	Required. A base URL that starts with http:// or https://, or the path of a JSON file
--type	The type of the document: manifest, account, accountSearch or view. Needed for a file the command cannot detect, and it overrides detection. Ignored for a URL, where each type is known
--account	An account id to read and validate, for a URL target
--header	"Name: value" sent with every request to a URL. Repeat it for several headers, such as a bearer token of your system

Each line starts with ok or fail, then the document type and its source. A fail is followed by one line per problem with its path and the rule it breaks:

Code
fail  account  bad.json
        $.title  is required
        $.sections  is required

Exit code	Meaning
0	Every document follows the format
1	At least one document does not
2	The command was used wrong: a missing argument, an unknown option or type, or a fixture that does not load

A document that cannot be read (a connection error, a status other than 2xx, or an answer that is not JSON) counts as a fail with the reason in the problem. Use the exit code in CI to stop a deploy that breaks the format. When the connector is registered, POST /v2/data-connectors/{id}/check validates the manifest your system really serves, and POST /v2/data-connectors/format/validate validates a document through the API.

lelemon connector serve

Code
lelemon connector serve --fixture <file> [--port 4300] [--secret <signing secret>]

serve starts a local HTTP server on 127.0.0.1 that answers the four requests of a connector from a fixture, so you can build the UI that reads it or point a registered connector at a tunnel before your own system exists.

Option	Default	Use
--fixture	none	Required. A JSON file with manifest, accounts and views
--port	4300	The port to listen on
--secret	none	A signing secret. With it, every request must carry a valid Lelemon signature and the server answers 401 invalid_signature otherwise. Without it, signatures are not checked

The fixture has three keys:

• manifest: the manifest document.
• accounts: a list of account cards. Each may carry an extra email, used only to answer GET /accounts?email= and never returned.
• views: an object that maps a view id to the page it returns.

The fixture is validated when it loads. A document that does not follow the format stops the command with exit code 2 and the failing paths, so you never serve something invalid by mistake.

The server answers GET only (405 otherwise) and these routes:

Route	Answers
/manifest	The manifest
/accounts?email=	The accounts whose email matches, as a list of { id, title, subtitle }
/accounts/{id}	The card, or 404 account_not_found
/views/{id}	The page, or 404 view_not_found

The command runs until you stop it with Ctrl+C. To test the signature check, pass the signing secret of the connector with --secret; see Verify that a call is from Lelemon.

What's next

• Connect your back office for the format, the registration and the copilot.
• TypeScript SDK for the connector helpers that build the documents in code.