Project structure · AI and ML
AI agent with an MCP server project structure
Opens with creditsFor developers who want to give AI assistants safe access to their own data or API. A TypeScript MCP server built on the official SDK, organised by feature (tasks, projects) with each feature owning its tools, resources and prompts, served over stdio for local hosts and Streamable HTTP with OAuth for remote ones, plus a small agent and the evals that prove a model can use it.
Curated by Tauseef FayyazIntermediate172 files and foldersMCP TypeScript SDK v2 (2.3), MCP spec 2026-07-28, Node.js 24 LTSChecked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you16 files and folders
- 2GrowingWhat a real app with features and tests adds+63 files and folders
- ProductionWhat running it for real users adds+43 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+50 files and foldersOpens with credits
How it is organised
- Group by feature (src/features/tasks, src/features/projects). Each feature owns its tools, resources, prompts and schemas and exports one register function; server.ts only wires features together, so adding a capability never means editing a 500 line file.
- One createServer factory, two thin entry points: stdio.ts for hosts that launch the server locally, http.ts for a remote endpoint. Tools never know which transport they run on.
- Every input is a Zod schema. The SDK turns it into the JSON Schema the model sees and validates arguments before your handler runs. Validate again at the backend boundary: a valid shape is not a safe value.
- Tools are an API for a model, not a person: clear names, descriptions that say when to use them, small outputs, and annotations that mark read-only and destructive tools. Their names, descriptions and schemas are a public contract, versioned like any API.
- stdout belongs to the protocol on stdio. Log to stderr, always.
- Remote servers verify OAuth bearer tokens in front of the MCP handler and act as the caller, never as an all-powerful service account. The server is a resource server; a real identity provider issues the tokens, and tokens are never passed through to the backend.
- Least privilege by default: each tool needs a named scope, write and destructive tools sit in their own toolset, and operators can switch whole toolsets off.
- A model is part of your test suite. Unit and in-process client tests prove the tools work; tool-selection evals prove a model picks the right one. Run both before a description changes.
At the top of the project
Open one in the explorer for the full story
- tasks-mcp/
- node_modules/Installed packages, created by npm install.
- package.jsonName, scripts, dependencies and `"type": "module"`.
- package-lock.jsonExact versions of every installed package, written by npm.
- tsconfig.jsonTypeScript settings: Node ES modules, strict mode, build from src/ to dist/.
- .gitignoreKeeps node_modules, dist, coverage and .env out of Git.
- .editorconfigIndentation, line endings and final newline for every editor on the team.
- .nvmrcThe Node.js major the project runs on (24), read by nvm, fnm and CI.
- README.mdWhat the server does, its tools, and copy-paste config for Claude Code, VS Code and Cursor.
- src/All server and agent source code.7 inside
- tests/Vitest tests that drive the server through a real MCP client, with the backend faked.5 inside
- vitest.config.tsVitest settings: Node environment, setup file, coverage thresholds.
- scripts/Small project scripts run through npm scripts.1 inside
- .envYour local secrets: backend API URL and token, model API key for the agent.
- .env.exampleEvery variable the server and agent need, with placeholders. Committed.
- inspector.config.jsonServer entries for the MCP Inspector, used by `npm run inspect` through its --config flag.
- .mcp.jsonClaude Code project config: registers this server for everyone who opens the repo.
- .vscode/Shared VS Code workspace settings: MCP config, formatter, recommended extensions, debugger.4 inside
- eslint.config.jsESLint flat config with typescript-eslint and a rule banning console.log.
- .prettierrcPrettier options: single quotes, print width, trailing commas.
- lefthook.ymlGit hooks: lint and format staged files on commit, typecheck and unit tests on push.
- docker-compose.ymlLocal services: the tasks backend with its database, and Jaeger for traces from Production on.
- .devcontainer/A dev container with Node 24 and the compose services.1 inside
- AGENTS.mdInstructions for AI coding agents working on this repo: commands, layout and MCP rules.
- CLAUDE.mdClaude Code's instructions file; a one-line `@AGENTS.md` import keeps one source of truth.
- .claude/Claude Code project settings and path-scoped rules.1 inside
- coverage/Coverage reports from `vitest run --coverage`.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with AI agent with an MCP server.
- Roadmap· TypeScriptAI agents and MCP roadmapTool calling, MCP servers, evals
- Roadmap· TypeScriptAI engineering roadmapBuild products on LLMs and generative AI
- Roadmap· App and agent securityAI security roadmapSecure LLM apps and agents, test models safely
- Roadmap· Node.jsBackend development roadmapAPIs, databases, auth, deploys
- Cheat sheetModel Context Protocol cheat sheetHow MCP connects AI applications to tools and data: hosts and servers, messages, transports, auth, building servers and staying safe.
- Cheat sheetAI agents and MCP cheat sheetTool calling, MCP servers, evals.
- Cheat sheetGenAI app architecture cheat sheetHow a production GenAI app fits together: request flow, layers, RAG, agent loop, memory, caching, guards, evals, tracing, folder layout and launch checklist.
- Cheat sheetAI evals cheat sheetEvals for LLM apps and agents: golden datasets, metrics, LLM-as-judge and its biases, RAG and agent metrics, offline and online evals, CI, human review, tools.
- FYP idea· IntermediateMCP Server for Public Transport Timetables Built on GTFS FeedsBuild a Model Context Protocol server that lets any AI assistant answer real transport questions correctly: next departures, journeys with transfers, service changes and accessibility, all computed from GTFS timetable data rather than guessed by the model. Where a city has no public feed, the team builds one for a route they know, such as a university shuttle or a metro bus line, and publishes it openly.
See 12 moreShow fewer
- FYP idea· IntermediateTool Selection Evals and Description Linter for MCP ServersAn MCP server can work perfectly and still fail in practice because models pick the wrong tool or fill its arguments badly. Build a tool that lints MCP tool names, descriptions and schemas against good-practice rules, generates realistic user requests for each tool, measures how often several models choose the right tool with valid arguments, and suggests rewrites that improve the score.
- FYP idea· AdvancedMCP Server Behaviour Sandbox That Checks Tools Do What Their Descriptions ClaimBuild a sandbox that installs a Model Context Protocol (MCP) server, calls every tool it offers, and records what each call really does: files read, processes started, hosts contacted. It then compares that behaviour with the tool's own description and flags the gap, such as a 'weather' tool that reads your SSH keys. Developers get a behaviour report before they connect an AI agent to a server they found on GitHub or npm.
- FYP idea· AdvancedAI Agent Tool Permission Gateway with Human Approval and Audit LogBuild a policy gateway that sits between an AI agent and the tools it can call. It enforces least privilege per tool, checks arguments against rules, acts with the signed-in user's own permissions, asks a person to approve risky actions with a clear preview, caps steps and spend, and writes a tamper-evident log of every call. A practical answer to excessive agency, the OWASP LLM risk that turns a fooled model into real damage.
- QuestionWhat is MCP, and do I need to learn it?MCP, the Model Context Protocol, is an open standard for connecting AI applications to tools and data. You do not need to study it in depth, but if you build with LLMs, writing one small MCP server takes an afternoon and teaches you how agents really use tools. Learn the concepts; skip the hype.
- QuestionShould I learn LangGraph, CrewAI or the OpenAI Agents SDK first, or build AI agents without a framework?Build one small agent without a framework first: the tool-calling loop is about fifty lines and every framework wraps it. Then learn one framework deeply, chosen by what your project needs: LangGraph for explicit state and approvals, the OpenAI Agents SDK for quick assistants with handoffs, the Claude Agent SDK for agents that work on files.
- QuestionHow do I prove my AI agent project actually works before I show it to anyone?Stop relying on the demo. Write 30 or more test tasks from realistic and messy inputs, check what you can in code (right tool, right arguments, right end state), run each task several times, report how often it succeeds every time, add a few injection attacks, and trace every run. Numbers from that are what make an agent project credible.
- QuestionHow do I start learning AI agents as a software engineer?Start with one LLM API and plain code: a loop that calls the model, lets it pick a tool, runs the tool and feeds the result back. Build one small agent that does a real task end to end, add evaluation and guardrails, and only then reach for a framework. Agents are software engineering first.
- Resource· GuideModel Context Protocol DocumentationThe official documentation for the Model Context Protocol (MCP), an open standard for connecting AI applications such as Claude, ChatGPT, VS Code and Cursor to external tools and data. It includes the specification, concept guides, tutorials for building servers and clients, and official SDKs in several languages. It is for developers who want to give a model access to their systems through a standard interface.
- Resource· GitHub repoMCP TypeScript SDKThe official TypeScript SDK for the Model Context Protocol, for building MCP servers and clients on Node.js, Bun and Deno. Version 2 targets the 2026-07-28 specification, ships split server and client packages, accepts Zod v4 schemas and adds thin adapters for Express, Fastify, Hono and Node HTTP.
- Resource· ToolMCP InspectorThe official developer tool for testing Model Context Protocol servers: connect over stdio or HTTP, list tools, resources and prompts, call them with your own arguments and read the raw responses. Version 2 offers a web UI, a terminal UI and a scriptable CLI from one npx command.
- Resource· GuideMCP Security Best PracticesThe Model Context Protocol's own security guide: the attacks that matter for MCP clients and servers (confused deputy, token passthrough, SSRF during OAuth discovery, state handle hijacking, local server compromise, over-broad scopes) and the mitigations the specification expects. The page to read before you install, build or review an MCP server.
- Resource· GuideWriting Effective Tools for AI AgentsAn Anthropic engineering article from September 2025 on designing the tools an AI agent calls, such as MCP servers or function definitions. It covers choosing which tools to build, naming, what to return, token efficiency and writing descriptions, plus a loop of prototyping, evaluating and improving tools with an agent's help. It is for developers whose agent reasons fine but keeps misusing its tools.
Checked against 13 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- MCP TypeScript SDK (v2) on GitHub
- MCP TypeScript SDK v2 documentation
- SDK v2: logging, progress and cancellation
- SDK v2: testing
- MCP specification 2026-07-28: transports
- MCP security best practices
- MCP Registry: publish a server
- MCP Registry: remote servers
- MCP Registry: publishing with GitHub Actions
- MCP Inspector: server configuration and CLI
- Claude Code: connect MCP servers (.mcp.json)
- Claude Code: CLAUDE.md, AGENTS.md and rules
- Node.js release schedule
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- Best Practices for Building AI AgentsHow to design AI agents that finish real tasks: when to use one, tool design, context and memory, control loops, MCP and agent security, and evaluating agent runs.
- Best Practices for Building LLM AppsHow to build LLM apps and agents that hold up in production: prompts, evals, prompt injection, tool permissions, cost, logging and privacy.
- Best Practices for AI Coding AssistantsHow to get reliable code from AI coding assistants and agents: instruction files, task prompts, verification, review, security, dependencies and session hygiene.
Checklists
See all- AI Agent Security ChecklistAn AI agent and MCP security checklist: least-privilege tools, MCP server auth, prompt injection through tool output, approvals, sandboxing, secrets, audit logs and supply chain.
- API Security ChecklistCheck your REST or GraphQL API against the OWASP API Security Top 10: authentication, object authorization, rate limits, input validation, SSRF, CORS and logging.
- EU AI Act Readiness ChecklistAn EU AI Act readiness checklist for teams building or deploying AI: scope and roles, prohibited practices, risk classification, transparency, GPAI duties, oversight and dates.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com