Skip to main content

🧩 Developer guide

Follow this guide if you want to build Lokka from source to contribute to the project.

Pre-requisites​

Building the project​

  • Open a terminal and navigate to the Lokka project directory.

  • Change into the folder \src\mcp\

  • Run the following command to install the dependencies:

    npm install

  • After the dependencies are installed, run the following command to build the project:

    npm run build

  • When the build is complete, you will see a main.js file find the compiled files in the \src\mcp\build\ folder.

Configuring the agent​

  • In Claude Desktop, open the settings by clicking on the hamburger icon in the top left corner.

  • Select File > Settings (or press Ctrl + ,)

  • In the Developer tab, click Edit Config

  • This opens explorer, edit claude_desktop_config.json in your favorite text editor.

  • Add the following configuration to the file, using the information you in the Overview blade of the Entra application you created earlier.

  • Note: On Windows the path needs to be escaped with \\ or use / instead of \.

    • E.g. C:\\Users\\<username>\\Documents\\lokka\\src\\mcp\\build\\main.js or C:/Users/<username>/Documents/lokka/src/mcp/build/main.js

  • Tip: Right-click on build\main.js in VS Code and select Copy path to copy the full path.

{
  "mcpServers": {
      "Lokka-Microsoft": {
          "command": "node",
          "args": [
              "<absolute-path-to-main.js>/src/mcp/build/main.js"
          ],
          "env": {
            "TENANT_ID": "<tenant-id>",
            "CLIENT_ID": "<client-id>",
            "CLIENT_SECRET": "<client-secret>"
          }
      }
  }
}
  • Exit Claude Desktop and restart it.
    • Every time you make changes to the code or configuration, you need to restart Claude desktop for the changes to take effect.
    • Note: In Windows, Claude doesn't exit when you close the window, it runs in the background. You can find it in the system tray. Right-click on the icon and select Quit to exit the application completely.

Testing the agent​

Testing with Claude Desktop​

  • Open the Claude Desktop application.
  • In the chat window on the bottom right you should see a hammer icon if the configuration is correct.
  • Now you can start quering your Microsoft tenant using the Lokka agent tool.
  • Some sample queries you can try are:
    • Get all the users in my tenant
    • Show me the details for John Doe
    • Change John's department to IT - Needs User.ReadWrite.All permission to be granted

Testing with MCP Inspector​

MCP Inspector is a tool that allows you to test and debug your MCP server directly (without an LLM). It provides a user interface to send requests to the server and view the responses.

See the MCP Inspector for more information.

npx @modelcontextprotocol/inspector node path/to/server/main.js args...

Releasing a new version​

Releases are fully automated with GitHub Actions — publishing a new build is a single click and you never edit version numbers by hand.

Publishing a new build (patch release)​

  1. Go to the repo's Actions tab → Publish to npm → Run workflow.
  2. Click Run workflow (leave all the defaults).

That's it. The workflow:

  • bumps the patch version automatically (e.g. 2.0.0 → 2.0.1),
  • builds the server and all the interactive app bundles,
  • runs the full UI test suite (the publish is blocked if any test fails),
  • publishes to npm with provenance attestation,
  • commits the version bump back to main (commit message Release vX.Y.Z).

Major or minor version upgrades​

Use the same workflow — just pick a different option in the Version bump dropdown when running it:

BumpExampleWhen to use
patch (default)2.0.0 → 2.0.1Bug fixes, small tweaks — the everyday release
minor2.0.5 → 2.1.0New features, backwards compatible
major2.1.3 → 3.0.0Breaking changes

There is no need to edit package.json manually — the workflow computes the new version, publishes it and commits it back.

Where the version number lives​

src/mcp/package.json is the single source of truth. Everything else derives from it automatically:

  • the MCP server reports it to clients at runtime (read from package.json on startup),
  • the MCPB bundle manifest is synced from it at pack time,
  • npm publishes whatever it says.

Other workflow options​

  • dist-tag — publish under a different npm tag (e.g. next or beta) to ship a preview without changing what npx @merill/lokka resolves to.
  • Dry run — runs the whole pipeline (bump, build, test, pack) but publishes nothing and commits nothing. Useful for verifying a release before shipping it.
note

Publishing authenticates via npm trusted publishing (OIDC) — there are no npm tokens to manage or rotate. This is configured once on npmjs.com under the package's settings (Trusted Publisher → GitHub Actions → repo merill/lokka, workflow publish-npm.yml).

Learn about MCP​