Mcpsample

🚀 Simple MCP Server

This is a simple sample of an MCP (Model Context Protocol) server written in TypeScript. It can be used with ClaudeDesktop to perform file operations and retrieve system information.

🚀 Quick Start

Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Configure ClaudeDesktop: Edit the ClaudeDesktop configuration file (usually %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"],
      "env": {}
    }
  }
}

Important: Specify the absolute path to dist/index.js in the args array. 4. Restart ClaudeDesktop to apply the configuration.

Development Mode

During development, you can run the server directly with the following command:

npm run dev

✨ Features

Security Features

This MCP server incorporates a path access restriction feature, allowing access only to secure directories.

• Allowed Directories:
  • The user's Documents/00_AI_Area folder (current setting).
  • Other custom settings are possible.
• Blocked Directories:
  • System directories (e.g., /etc, /bin, /Windows, /Program Files).
  • Sensitive information directories (e.g., .ssh, .aws, .config).
• Allowed File Extensions: .txt, .md, .json, .js, .ts, .html, .css, .py, .java, .cpp, .c, .h, .xml, .yaml, .yml, .log, .csv, .tsv, .sql, .sh, .bat, .ps1

Functionalities

• read_file: Read files (only in allowed directories).
• write_file: Write to files (only in allowed directories).
• list_directory: List directory contents (only in allowed directories).
• get_system_info: Retrieve system information.
• create_sample_file: Create a sample file (for testing).
• get_allowed_paths: Display a list of accessible paths (New feature).

💻 Usage Examples

Try the following requests in ClaudeDesktop:

Retrieve System Information

Tell me the system information.

Check Accessible Paths

Show me the list of accessible paths.

Create a Sample File

Create a sample file named test.txt.

Read a File

Read the contents of test.txt.

List Directory Contents

List the contents of the current directory.

Write to a File

Write "Hello, MCP World!" to hello.txt.

🔧 Technical Details

Customizing Settings

You can customize access permission rules by modifying the settings of the PathValidator class:

// Add allowed directories
this.allowedPaths = [
  path.resolve(os.homedir(), 'Documents/00_AI_Area'),
  // Add custom paths
  path.resolve('/path/to/your/allowed/directory'),
];

// Add allowed file extensions
this.allowedExtensions = [
  '.txt', '.md', '.json',
  // Add new extensions
  '.custom',
];

File Structure

simple-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript files
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Troubleshooting

MCP Server Not Recognized

1. Check if the path in the ClaudeDesktop configuration file is correct.
2. Verify the absolute path to dist/index.js.
3. Ensure that the build was completed successfully with npm run build.
4. Restart ClaudeDesktop completely.

Errors in File Operations

• Check if the file path exists.
• Ensure that you have appropriate read and write permissions.
• Try using absolute paths instead of relative paths.

Security-Related Errors

• "Path is not allowed":
  • The path you are trying to access is not within an allowed directory.
  • Use the get_allowed_paths tool to check accessible paths.
• "File extension is not allowed":
  • You are trying to access an unsupported file extension.
  • Check the list of allowed extensions and modify the settings if necessary.

Debug Mode

The server's operation logs are output to the standard error output:

npm run dev 2> debug.log

Customization

To add a new tool:

1. Add a new tool definition to the TOOLS array.
2. Add a handler to the setupToolHandlers() method.
3. Implement the corresponding method. For example, if you want to add a tool to get the current time, you can implement a tool like get_current_time.

🛡️ Security Considerations

• Path Access Restriction: Prevent unauthorized access to system files and sensitive information.
• File Extension Filtering: Block executable files and dangerous file formats.
• Path Normalization: Prevent unauthorized access to parent directories using relative paths or ...
• Error Handling: Notify security violations with appropriate error messages.

❓ Frequently Asked Questions

Q: How can I access a new directory?

A: Add the path to the allowedPaths array in the PathValidator class and restart the server.

Q: Can I disable the security restrictions?

A: Although it is not recommended for security reasons, you can modify the validatePath method to always return { isValid: true, normalizedPath }.

Q: Can it handle large files?

A: The current implementation reads the entire file into memory, so it is not suitable for handling very large files.

⚠️ Notes

• This sample is created for learning and testing purposes.
• When using it in a production environment, add appropriate error handling and security measures.
• File operations are performed with the permissions of the executing user.
• Due to security restrictions, you cannot access directories other than the allowed ones.

Strictly Note: This server is intended for local use. When using it in a production environment, consider additional security measures.

📄 License

MIT License