DEV Community: Jonas Gauffin

Live API specs for coding agents

Jonas Gauffin — Sun, 30 Aug 2026 12:33:00 +0000

Live API specs for coding agents

An agent writing frontend code has to know the backend's API. It has three options. It can read the backend source and work out from scratch what the service already publishes. It can ask you, which promotes you to API documentation. Or it can swallow the entire OpenAPI document in order to use one route out of it.

Then it does the same thing again tomorrow, against a stale swagger.json you exported last week.

docs-mcpserver takes the spec straight from the running service, caches it, and serves it one operation at a time.

The config

{
  "cacheDir": "./cache",
  "libraries": [
    {
      "name": "orders-api",
      "description": "Order handling service",
      "sources": [
        {
          "type": "url",
          "origin": "https://localhost:5001/openapi/v1.json",
          "kind": "schema",
          "name": "orders"
        }
      ]
    }
  ]
}

npm install -g docs-mcpserver
claude mcp add docs -- docs-mcpserver --config /path/to/dev-docs.json

That is the whole setup.

One operation, not the whole spec

The agent lists the definitions in orders, picks the one it needs, and fetches that. For an OpenAPI document the path operations are exposed as definitions named GET /orders/{id}, so it can also search by keyword.

A few hundred tokens for the operation it is writing against, instead of the entire document. That keeps working as the service grows, which a pasted spec does not.

The backend does not have to be running

Every call is answered from the cached spec, never from the network. The fetch happens on startup and then in the background while you work, so an endpoint you added 20 seconds ago is already visible.

Start the backend once, shut it down, and keep building the frontend. The agent still has real routes and real payload shapes. If the service is down, or answers with something that is not a spec, the last known-good copy keeps being served.

Code and issues: github.com/jgauffin/dev-docs-mcp. On npm as docs-mcpserver.

Giving AI agents knowledge they were never trained on

Jonas Gauffin — Thu, 14 May 2026 22:02:53 +0000

I love coding my own stuff, and my clients typically have lots of internal specifications and libraries to use.

But since LLMs haven't been trained on that, it's hard to get them to code accurately using those specs, libraries, or frameworks.

You can, of course, let the agents parse everything, but that wastes tokens and your patience :)

The same goes for well-known libraries, but you are stuck on a specific version that you must follow. You don't want it to guess the API.

docs-mcpserver exists to deal with both.

What it is

It is an MCP server that provides an agent with accurate knowledge of a framework or specification using documentation as the medium. It reads three kinds of docs:

Markdown docs — your *.md files.
API reference — C# XML documentation, or TypeDoc JSON.
Schema — JSON Schema, OpenAPI 3.x, Swagger 2.0.

What the agent gets out of it is the same in every case: the real names, the real
signatures, the real shapes. Sources can come from a
local folder or straight from a GitHub URL. A single
server instance can host several libraries side by side. For instance, your in-house framework, a client's framework, and a specific version of some public library.

The agent picks which one to query.

I personally have used it to code against a specification called DATEX (traffic information for roads), which is HUGE, my own SPA library, and against sound format specifications for a sound app I'm building.

Why not just give the agent the files

You could point the agent to the folders and let it read them. The MCP server does a few things that raw file access does not:

It is sandboxed. Each source is scoped, with path-traversal protection. The agent reads what you exposed, nothing else on the disk.
It reads in pieces. Instead of loading a 4000-line reference file, the agent asks for the table of contents, then pulls the one chapter it needs.
It searches properly. Dedicated search tools with regex and glob support, instead of the agent improvising its own grep.
It is self-describing. With several libraries configured, the agent calls one tool to discover what is available. You do not have to spell out every path.
GitHub works without cloning. Give it a repo URL and it handles the rest.

The multi-library part is the point. Instead of running several MCP servers for
documentation, you get one with a small toolset. No token waste.

Setting it up

Install and build:

npm install
npm run build

The quick way, a single folder:

docs-mcpserver ./docs --name "My Docs"

For the real use case — several libraries — use a config file. Here is an
in-house framework served from disk, next to a pinned version of a public
library pulled from GitHub:

{
  "name": "dev-docs",
  "description": "Frameworks the model has not been trained on",
  "cacheDir": "./cache",
  "libraries": [
    {
      "name": "acme-core",
      "description": "Our internal application framework",
      "sources": [
        { "type": "disk", "origin": "./frameworks/acme-core/docs", "kind": "docs" },
        { "type": "disk", "origin": "./frameworks/acme-core/api",  "kind": "api"  }
      ]
    },
    {
      "name": "somelib-3.2",
      "description": "SomeLib, pinned to v3.2.0",
      "sources": [
        {
          "type": "github",
          "origin": "https://github.com/someorg/somelib/tree/v3.2.0/docs",
          "kind": "docs"
        }
      ]
    }
  ]
}

Start it with the config:

docs-mcpserver --config dev-docs.json

And register it with Claude Code:

claude mcp add mydocs -- node /path/to/markdown-docs-mcp/dist/index.js --config /path/to/dev-docs.json

For private GitHub repos, set GITHUB_TOKEN in the environment.

What the agent actually sees

Each library exposes tools based on the kind of its sources:

docs — get_doc_index, get_sub_index, read_doc_file, get_file_toc, get_chapters, search_docs.
api — get_api_index, get_api_type, get_api_member, search_api.
schema — list_schemas, list_definitions, get_definition, search_definitions, search_all_schemas.

A typical run looks like this. The agent calls list_libraries and sees
acme-core and somelib-3.2. It needs to know how acme-core handles
configuration, so it calls search_docs with library: "acme-core", finds the
right file, asks for its table of contents with get_file_toc, then pulls the
one relevant section with get_chapters. It answers the question without ever
loading the whole file.

When multiple libraries are configured, every tool takes a library parameter.
When there is only one, the parameter disappears, and the tools behave like a
plain single-library server.

The same applies to schema sources. For an OpenAPI spec, path operations show up
as definitions named like GET /pets, so the agent can ask for one endpoint
without reading the whole document. Useful when you want the agent to call your
API correctly rather than guess at the shape of it.

Generating the API input

One thing worth knowing up front: the api pipeline does not read source code.
It consumes a generated documentation file.

TypeScript / JavaScript — use TypeDoc's JSON serializer: typedoc --json api.json src/index.ts. Point the source at that .json file. The markdown output from typedoc-plugin-markdown is not supported — it has to be the JSON serializer output.
C# — enable <GenerateDocumentationFile>true</GenerateDocumentationFile> and point the source at the generated *.xml file, or the build output folder that contains it.

What it does not do

It does not read source code. If you want API reference, you generate the doc
file first, as above.

Try it

The code is on GitHub, or on npm as docs-mcpserver.

Feel free to leave feedback, or check my other MCP servers on GitHub.

Exception handling explained

Jonas Gauffin — Thu, 10 May 2018 11:33:24 +0000

This article explains what exception handling is and how it differs from
traditional error handling with error codes. The article does not get
into usage or exception classes, but only to explain their purpose.

Let's start with errors.

A brief introduction to error

From the dawn of programming, error codes have been used to deal with errors in applications. An error code is used to indicate if the
executed function was successful or not.

Here is a simple example:

public bool SaveDefaultAccount(string userName, string accountName)
{
    int userId = GetUserIdFromName(userName);
    if (userId == -1)
        return false;

    int accountId = GetAccountFromName(accountName);
    if (accountId == -1)
        return false;

    return StoreDefaultAccount(userId, accountId);
}

The example illustrates that when you use error codes, it is the API
consumer that must abort if something fails. You might, but how about
the rest of the team, or those who maintained the application before
you? It is like you would retire the entire police force and expect
all citizens to behave and be good law abiding citizens.

One developer could have been lazy and just written (or refactored) the
code as:

public bool SaveDefaultAccount(string userName, string accountName)
{
    int userId = GetUserIdFromName("Arne");
    int accountId = GetAccountFromName("Savings account");
    return StoreDefaultAccount(userId, accountId);
}

The problem is that the code looks perfectly legal, but silently ignores
errors. If you for instance mistakenly add a white space after all
account names on the account selection page, the code above starts to
fail silently. What's worse is that you will not know about it until
code dependent upon the default account starts to fail, and that can be
after a while. Tracking down that subsequent error can be challenging,
primarily if the default account is set in different ways.

Error codes are easy to get started with and can be quite powerful. Even
modern languages like Go-lang uses errors instead of exceptions. Here is
a go snippet:

f, err := os.Open("filename.ext")
if err != nil {
    log.Fatal(err)
}

While errors are easy to understand and use, they have three
significant drawbacks:

They do not convey context

This section is for languages that only uses error codes.

For instance, error code 2 means "File Not Found" in Windows. There is
no way to state which file nor other information that might help you to
understand why the file was missing. Error codes are just that. Codes
that indicate a specific error, without context or clues.

The problem with that is that it is hard to understand why or under what
circumstances that the error occurred. The Windows API solves this by
introducing a method called GetLastError() which is used to get more
information about the error.

OFSTRUCT buffer;
HFILE hFile = OpenFile("d:\\sample.txt", &buffer, OF_READ);
if (hFile == HFILE_ERROR)
{
    // all this is required to get the error message.
    // you typically add it to a separate function

    // Get the error code, as hFile only indicates an error
    // but not which one.
    var errorCode = GetLastError();

    // Get the generic error message which
    // represents the above error code.
    LPVOID lpMsgBuf;
    LPVOID lpDisplayBuf;
    FormatMessage(
        FORMAT_MESSAGE_ALLOCATE_BUFFER | 
        FORMAT_MESSAGE_FROM_SYSTEM |
        FORMAT_MESSAGE_IGNORE_INSERTS,
        NULL,
        errorCode,
        MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
        (LPTSTR) &lpMsgBuf,
        0, NULL );
}

My point is that an error code is not enough when you want to
solve the error.

The burden is on the function caller

It is safe to say that all applications have errors, it is exceptionally
rare (pun intended) that errors can be ignored. Ignoring errors might
seem to work, but sooner or later consequential problems will surface.
It will be much harder to find the root cause since the found error is
just a consequence of the first one. Any kind of "fix" is just a
workaround which clutters the code base but does not prevent the root
cause from happening again.

It is crucial that all errors are handled in your code. When you use
error codes, it is so easy to ignore or forget errors. Had a tight
deadline? Wrestled with an obscure bug or incomprehensible requirements?
Those situations make it so easy to take a shortcut. If not all
developers on your team have the same discipline, errors will get
ignored.

Enter exceptions

Exceptions are for exceptional situations. If something didn't go as
expected, you got an exceptional situation.

Sounds easy, huh?

But what does that mean?

An exceptional example

If you expect that something can fail, you should guard against that
situation.

Here is an example:

Let's say that you love shopping the newest and hottest technical
gadgets. When the new gadget is released, you want to be first.

Scenario 1

If you are like most of us, you can probably not just go on a shopping
spree. You need to make sure that you have enough money.

Check your bank account.
Go shopping.
Pay

Scenario 2

However, if you are fortunate enough to have plenty of money, you can
go shopping directly:

Go shopping.
Pay

The difference

In the first scenario, we have a known issue that we need to deal with:
A money limit. Therefore, we always need to check that we have enough
money. In the second scenario, we should have enough money.

What happens if someone has hacked us in scenario 2:

Someone hacked us
Go shopping
Pay <-- Failed, no money

In that case, we got an exception, since it is a case that shouldn't
happen since we expect to have enough money.

That is an exceptional situation.

Why can't we always write the code like in scenario 1?

First, it's about communicating intent. We mostly get a set of business
requirements that we should fulfill. They tell us what to expect when
implementing different use cases. If we go and add many checks for
things that might, but should not, happen we lose the connection between
our use cases and the code. It will be hard to tell the intent of the
code, which in turn lead to assumptions and in the end decreased code
quality.

Second, if we add many checks we are coding workarounds as the real
problem is that our account was hacked, not that we could not pay. By
adding checks and abort instead of paying we are hiding that fact.

What exceptions are

Exceptions are for situations that wasn't considered when defining what
the application should do. When writing a messaging library for message
queues you expect to receive complete messages, but when you write one
for TCP you expect to receive partial messages. What's exceptional in
one case doesn't necessarily have to be exceptional in another.

If you would open a file there are several errors that can happen.
Non-existent directory, file is missing, access denied, partial file,
etc. All those errors are known to most programmers, so they are not
exceptions, right?

Wrong. In most cases, they are exceptions. Because you typically do
expect that a file exists and that it's complete and readable. Well, if
you are writing a data forensics application, most of those errors are
expected and should be dealt with (and therefore not exceptional cases).

Exceptions exist to prevent your application from doing something stupid.

It's crucial for you to understand that. Don't think of exceptions as
something you can use to control your application when coding. Think of
exceptions as a mechanism to guard against your application doing
something wrong/unexpected.

Exceptions exist to help you fix problems in the future

Since exceptions are not a flow control mechanism, they do add little
value when executing your code (previously described point excluded).

However, writing informative exception messages makes it much easier to
correct future bugs, since they add context to the error. Always try to
do so, your future self will thank you for it.

Code example

Let's take the same code as was found in the beginning of this article,
but changed to use exception handling instead.

public void SaveDefaultAccount(string userName, string accountName)
{
    int userId = GetUserIdFromName("Arne");
    int accountId = GetAccountFromName("Savings account");
    StoreDefaultAccount(userId, accountId);
}

As you can see, the method now returns void as it does not need to
indicate that everything went successfully. Nor does it need to validate
error codes from the called methods. One can safely assume that an
exception abort the processing if the expected result cannot be
guaranteed.

In fact, in most cases, we do not have to care if exceptions are thrown
at all. Remember, exceptions are used to communicate that something
unexpected happened. If we cannot predict it, how on earth could we be
able to handle the exception?

Let's look at the StoreDefaultAccount method. The most important thing
to understand is that the method says that a default account should be
stored successfully. Since that is the method promise, we must throw an
exception every time we find something that would prevent the default
account from being stored.

public void StoreDefaultAccount(int userId, int accountId)
{
    if (userId <= 0)
        throw new ArgumentOutOfRangeException(nameof(userId), userId,
            "A valid user id must be specified.");
    if (accountId <= 0)
        throw new ArgumentOutOfRangeException(nameof(accountId), accountId,
            "A valid account id must be specified.");

    var account = _accountRepository.GetById(accountId);
    if (account.OwnerId != accountId)
        throw new InvalidOperationException($"User {userId} do not own account {accountId}.");

    var user = _userRepository.GetById(userId);
    user.DefaultAccount = accountId;
    _userRepository.Update(user);
}

The first two exceptions are used to mitigate errors like parse errors
or invalid data.

The third exception is for a business rule. We may only use the user's
own accounts as default accounts.

_accountRepository.GetById(accountId); will in turn throw an
exception if the given accountId do not exist in the database since the
method name states that an account should be fetched.

Summary

The purpose of exceptions is not to allow you to take different actions
depending on if something failed or not. i.e. they are not a flow
control mechanism. Instead, exceptions are used to make sure that your
application delivers the expected result (or die trying).

With that in mind, I hope that you find them as useful as I do. With
the right mindset (and using exceptions) you can save much time since
you do not have to track down why your database has a lot of data
inconsistencies (which leads to bugs later).

This article is part of our exception handling series. To learn more, visit our website.