|
| 1 | +# Project Overview |
| 2 | + |
| 3 | +This project is a server implementing the MCP (Model Context Protocol) that allows users to interact with their MongoDB clusters |
| 4 | +and MongoDB Atlas accounts. It is built using TypeScript, Node.js and the official Anthropic |
| 5 | +@modelcontextprotocol/sdk SDK. |
| 6 | + |
| 7 | +## Folder Structure |
| 8 | + |
| 9 | +- `/src`: Contains the source code of the MCP Server. |
| 10 | +- `/src/tools`: Contains the implementation of MCP tools. |
| 11 | +- `/src/tools/atlas/`: Contains the implementation of MCP tools that are specific to MongoDB Atlas. |
| 12 | +- `/src/tools/mongodb/`: Contains the implementation of MCP tools that are specific to MongoDB clusters. |
| 13 | +- `/src/resources`: Contains the implementation of MCP Resources. |
| 14 | +- `/tests`: Contains the test code for the MCP Server. |
| 15 | +- `/tests/accuracy`: Contains the test code for the accuracy tests, that use different models to ensure that tools have reliable descriptions. |
| 16 | +- `/tests/integration`: Contains tests that start the MCP Server and interact with it to ensure that functionality is correct. |
| 17 | +- `/tests/unit`: Contains simple unit tests to cover specific functionality of the MCP Server. |
| 18 | + |
| 19 | +## Libraries and Frameworks |
| 20 | + |
| 21 | +- Zod for message and schema validation. |
| 22 | +- Express for the HTTP Transport implementation. |
| 23 | +- mongosh NodeDriverServiceProvider for connecting to MongoDB. |
| 24 | +- vitest for testing. |
| 25 | +- @modelcontextprotocol/sdk for the protocol implementation. |
| 26 | + |
| 27 | +## Coding Standards |
| 28 | + |
| 29 | +- For declarations, use types. For usage, rely on type inference unless it is not clear enough. |
| 30 | +- Always follow the eslint and prettier rule formats specified in `.eslint.config.js` and `.prettierrc.json`. |
| 31 | +- Use classes for stateful components and functions for stateless pure logic. |
| 32 | +- Use dependency injection to provide dependencies between components. |
| 33 | +- Avoid using global variables as much as possible. |
| 34 | +- New functionality MUST be under test. |
| 35 | + - Tools MUST HAVE integration tests. |
| 36 | + - Tools MUST HAVE unit tests. |
| 37 | + - Tools MAY HAVE accuracy tests. |
| 38 | + |
| 39 | +## Architectural Guidelines and Best Practices |
| 40 | + |
| 41 | +Every agent connected to the MCP Server has a Session object attached to it. The Session is the main entrypoint for |
| 42 | +dependencies to other components. Any component that MUST be used by either a tool or a resource MUST be provided |
| 43 | +through the Session. |
| 44 | + |
| 45 | +### Guidelines for All Tools |
| 46 | + |
| 47 | +- The name of the tool should describe an action: `create-collection`, `insert-many`. |
| 48 | +- The description MUST be a simple and accurate prompt that defines what the tool does in an unambiguous way. |
| 49 | +- All tools MUST provide a Zod schema that clearly specifies the API of the tool. |
| 50 | +- The Operation type MUST be clear: |
| 51 | + - `metadata`: Reads metadata for an entity (for example, a cluster). Example: CollectionSchema. |
| 52 | + - `read`: Reads information from a cluster or Atlas. |
| 53 | + - `create`: Creates resources, like a collection or a cluster. |
| 54 | + - `delete`: Deletes resources or documents, like collections, documents or clusters. |
| 55 | + - `update`: Modifies resources or documents, like collections, documents or clusters. |
| 56 | + - `connects`: Connects to a MongoDB cluster. |
| 57 | +- If a new tool is added, or the tool description is modified, the accuracy tests MUST be updated too. |
| 58 | + |
| 59 | +### Guidelines for MongoDB Tools |
| 60 | + |
| 61 | +- The tool category MUST be `mongodb`. |
| 62 | +- They MUST call `this.ensureConnected()` before attempting to query MongoDB. |
| 63 | +- They MUST return content sanitized using `formatUntrustedData`. |
| 64 | +- Documents should be serialized with `EJSON.stringify`. |
| 65 | +- Ensure there are proper timeout mechanisms to avoid long-running queries that can affect the server. |
| 66 | +- Tools that require elicitation MUST implement `getConfirmationMessage` and provide an easy-to-understand message for a human running the operation. |
| 67 | + - If a tool requires elicitation, it must be added to `src/common/config.ts` in the `confirmationRequiredTools` list in the defaultUserConfig. |
| 68 | + |
| 69 | +### Guidelines for Atlas Tools |
| 70 | + |
| 71 | +- The tool category MUST be `atlas`. |
0 commit comments