ai-agents-mcp-typescript

A minimal, readable template for building AI agents in TypeScript that use tools over the Model Context Protocol (MCP). It includes a working MCP file server, an MCP client, and a bounded agent loop. Fork it and replace the tools and the LLM provider with your own.

Features

• MCP over stdio: a server (server.ts) exposes tools, and the agent (agent.ts) connects as a client and discovers them at runtime.

• Explicit agent loop: Perceive, Decide, Act, Observe, Repeat. Each phase is a small, separately tested module in phases/.

• Provider-agnostic LLM interface: the loop depends on an LLMProvider interface. An Anthropic implementation using plain fetch is included.

• Safe by default: the loop stops after a maximum number of iterations, and oversized tool results are truncated before they reach the model.

• No build step: Node runs the TypeScript sources directly.

• Tested: unit tests with Vitest sit next to the code they cover.

Related MCP server: MCP File Manager

Architecture

flowchart LR
  subgraph Agent["agent.ts (MCP client)"]
    P[PERCEIVE<br/>list tools] --> D[DECIDE<br/>ask the LLM]
    D -->|tool calls| A[ACT<br/>call tools]
    A --> O[OBSERVE<br/>append results]
    O -->|repeat| D
    D -->|no tool calls| R[Final answer]
  end

  D <-->|HTTPS| L[(Anthropic<br/>Messages API)]
  P <-->|MCP over stdio| S
  A <-->|MCP over stdio| S[server.ts<br/>list_files, read_files]

Requirements

• Node.js 22.18 or later

• pnpm 10

• An Anthropic API key

Quick start

pnpm install
cp .env.example .env   # then set ANTHROPIC_API_KEY in .env
pnpm agent "List the files in the current directory and summarize what this project does"

The prompt is the first command-line argument. Without one, the agent lists the files in the current directory. The agent starts the MCP server itself, so you do not need to run pnpm server separately.

Configuration

Extending the template

Add a tool. Register it in server.ts with server.registerTool(name, { description, inputSchema }, handler). The agent discovers it on the next run.

Use another LLM. Implement the LLMProvider interface from llm/types.ts, which is a single chat(messages, tools) method, and pass your provider to runAgent. See llm/anthropic.ts for a reference implementation.

Use another tool backend. runAgent only needs a ToolExecutor (a callTool method), so it works with any MCP client, or with a stub in tests.

Development

pnpm test        # run the Vitest suite once
pnpm typecheck   # tsc --noEmit
pnpm server      # run the MCP server standalone (speaks MCP on stdio)

.
├── agent.ts        # entry point: connects to the server and runs the agent
├── server.ts       # MCP file server (list_files, read_files)
├── llm/            # provider interface and Anthropic implementation
└── phases/         # perceive, decide, act, observe, repeat (with tests)

Security

• The list_files and read_files tools accept any path and can read anything the user running the agent can access. They are not restricted to a project directory.

• Your prompt, and the contents of any files or directories the model reads, are sent to the Anthropic API.

• Run the agent only in directories that contain nothing sensitive, and restrict paths in server.ts before using it with real data.

• Never commit your .env file. It is listed in .gitignore.

License

MIT