{"id":30538479,"url":"https://github.com/toby/mirror-mcp","last_synced_at":"2026-01-20T18:07:35.064Z","repository":{"id":306975488,"uuid":"1025287905","full_name":"toby/mirror-mcp","owner":"toby","description":"🪞✨ Looking at yourself","archived":false,"fork":false,"pushed_at":"2025-07-28T22:37:21.000Z","size":109,"stargazers_count":9,"open_issues_count":10,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-16T16:38:27.308Z","etag":null,"topics":["mcp","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-24T03:21:07.000Z","updated_at":"2025-10-05T02:10:29.000Z","dependencies_parsed_at":"2025-07-28T19:51:30.453Z","dependency_job_id":"ffb8a642-71be-4e97-93bb-788471300c32","html_url":"https://github.com/toby/mirror-mcp","commit_stats":null,"previous_names":["toby/mirror-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/toby/mirror-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toby%2Fmirror-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toby%2Fmirror-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toby%2Fmirror-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toby%2Fmirror-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toby","download_url":"https://codeload.github.com/toby/mirror-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toby%2Fmirror-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28608095,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server"],"created_at":"2025-08-27T20:55:35.426Z","updated_at":"2026-01-20T18:07:35.042Z","avatar_url":"https://github.com/toby.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mirror-mcp\n\n[![npm version](https://badge.fury.io/js/mirror-mcp.svg)](https://badge.fury.io/js/mirror-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA Model Context Protocol (MCP) server that provides a `reflect` tool, enabling LLMs to engage in self-reflection and introspection through recursive questioning and MCP sampling.\n\n## Overview\n\n**mirror-mcp** allows AI models to \"look at themselves\" by providing a reflection mechanism. When an LLM uses the `reflect` tool, it can pose questions to itself and receive answers through the Model Context Protocol's sampling capabilities. This creates a powerful feedback loop for self-analysis, reasoning validation, and iterative problem-solving.\n\n## Features\n\n- 🪞 **Self-Reflection Tool**: Enables LLMs to ask themselves questions and receive computed responses\n- 🔄 **MCP Sampling Integration**: Uses the Model Context Protocol's sampling mechanism for responses\n- 📦 **npm Installable**: Easy installation and deployment\n- ⚡ **Lightweight**: Minimal dependencies and fast startup\n- 🔧 **Configurable**: Customizable reflection parameters and sampling options\n\n## Installation\n\n### Quick Install for VS Code\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=mirror\u0026config=%7B%22type%22%3A%20%22stdio%22%2C%20%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22mirror-mcp%40latest%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=mirror\u0026config=%7B%22type%22%3A%20%22stdio%22%2C%20%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22mirror-mcp%40latest%22%5D%7D\u0026quality=insiders)\n\n### MCP Host Configuration\n\nFor other MCP-compatible clients, add the following configuration:\n\n```json\n{\n  \"type\": \"stdio\",\n  \"command\": \"npx\", \n  \"args\": [\"mirror-mcp@latest\"]\n}\n```\n\n### Via npm\n\n```bash\nnpm install -g mirror-mcp\n```\n\n### Via npx (no installation required)\n\n```bash\nnpx mirror-mcp\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/toby/mirror-mcp.git\ncd mirror-mcp\nnpm install\nnpm run build\nnpm start\n```\n\n## API Reference\n\n### Tools\n\n#### `reflect`\n\nEnables the LLM to ask itself a question and receive a response through MCP sampling. The tool supports custom system and user prompts to help the LLM self-direct what kind of response it gets.\n\n**Self-Direction with Custom Prompts:**\n- **System Prompt**: Define the role or perspective for the reflection (e.g., \"expert coach\", \"critical thinker\", \"creative problem solver\")\n- **User Prompt**: Specify the format, structure, or focus of the reflection response\n- **Default Behavior**: When no custom prompts are provided, uses built-in reflection guidance focused on strengths, weaknesses, assumptions, and alternative perspectives\n\n**Parameters:**\n- `question` (string, required): The question the LLM wants to ask itself\n- `context` (string, optional): Additional context for the reflection\n- `system_prompt` (string, optional): Custom system prompt to direct the reflection approach\n- `user_prompt` (string, optional): Custom user prompt to replace the default reflection instructions\n- `max_tokens` (number, optional): Maximum tokens for the response (default: 500)\n- `temperature` (number, optional): Sampling temperature (default: 0.8)\n\n**Example:**\n```json\n{\n  \"name\": \"reflect\",\n  \"arguments\": {\n    \"question\": \"How confident am I in my previous analysis of the data?\",\n    \"context\": \"Previous analysis showed a 23% increase in user engagement\",\n    \"max_tokens\": 300,\n    \"temperature\": 0.6\n  }\n}\n```\n\n**Example with custom prompts:**\n```json\n{\n  \"name\": \"reflect\",\n  \"arguments\": {\n    \"question\": \"What are the potential weaknesses in my reasoning?\",\n    \"system_prompt\": \"You are an expert critical thinking coach helping to identify logical fallacies and reasoning gaps.\",\n    \"user_prompt\": \"Analyze my reasoning step-by-step and provide specific examples of potential weaknesses or blind spots.\",\n    \"context\": \"Working on a complex machine learning model evaluation\",\n    \"max_tokens\": 400,\n    \"temperature\": 0.7\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"reflection\": \"Upon reflection, my confidence in the 23% engagement increase analysis is moderate to high. The data sources appear reliable, and the methodology follows standard practices. However, I should consider potential confounding variables such as seasonal effects or concurrent marketing campaigns that might influence the results.\",\n  \"metadata\": {\n    \"tokens_used\": 67,\n    \"reflection_time_ms\": 1240\n  }\n}\n```\n\n## Architecture \u0026 Rationale\n\n### Design Philosophy\n\n**mirror-mcp** is built on the principle that self-reflection is crucial for robust AI reasoning. By enabling models to question their own outputs and reasoning processes, we create opportunities for:\n\n- **Error Detection**: Models can identify potential flaws in their logic\n- **Confidence Calibration**: Self-assessment helps gauge certainty levels\n- **Iterative Improvement**: Reflective questioning can lead to better solutions\n- **Metacognitive Awareness**: Understanding of the model's own reasoning process\n\n### Technical Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   LLM Client    │───▶│   mirror-mcp    │───▶│  MCP Sampling   │\n│                 │    │                 │    │   Infrastructure │\n│ Calls reflect() │    │ Processes       │    │                 │\n│                 │◀───│ reflection      │◀───│ Returns response│\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n```\n\n#### Key Components\n\n1. **Reflection Engine**: Processes incoming self-directed questions\n2. **Sampling Interface**: Interfaces with MCP's sampling capabilities\n3. **Context Manager**: Maintains conversation context for coherent reflections\n4. **Response Formatter**: Structures reflection responses for optimal consumption\n\n### Why MCP?\n\nThe [Model Context Protocol](https://github.com/modelcontextprotocol/modelcontextprotocol) provides a standardized way for AI models to connect with external resources and tools. By implementing mirror-mcp as an MCP server, we ensure:\n\n- **Interoperability**: Works with any MCP-compatible client\n- **Standardization**: Follows established protocols for tool integration\n- **Scalability**: Can be deployed alongside other MCP servers\n- **Future-Proofing**: Benefits from ongoing MCP ecosystem development\n\n### Sampling Strategy\n\nThe reflection mechanism leverages MCP's sampling capabilities to generate thoughtful responses. The sampling process:\n\n1. Takes the self-directed question as a prompt\n2. Applies configurable sampling parameters (temperature, max tokens)\n3. Generates a response using the underlying model\n4. Returns the reflection with appropriate metadata\n\nThis approach ensures that reflections are generated using the same model capabilities as the original reasoning, creating authentic self-assessment.\n\n## Development\n\n### Prerequisites\n\n- Node.js 18 or higher\n- npm or yarn\n- TypeScript (for development)\n\n### Development Setup\n\n```bash\ngit clone https://github.com/toby/mirror-mcp.git\ncd mirror-mcp\nnpm install\nnpm run dev\n```\n\n### Testing\n\n```bash\nnpm test\n```\n\n### Building\n\n```bash\nnpm run build\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Areas for Contribution\n\n- Enhanced reflection strategies\n- Additional sampling parameters\n- Performance optimizations\n- Documentation improvements\n- Test coverage expansion\n\n## Related Projects\n\n- **[Model Context Protocol](https://github.com/modelcontextprotocol/modelcontextprotocol)**: The foundational protocol specification\n- **MCP Ecosystem**: Various other MCP servers and tools\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- The Model Context Protocol team for creating the foundational specification\n- The broader AI research community working on metacognition and self-reflection\n- Contributors and early adopters who help shape this tool\n\n---\n\n\u003e *\"The unexamined life is not worth living\"* - Socrates\n\u003e \n\u003e Enable your AI models to examine their own reasoning with mirror-mcp.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoby%2Fmirror-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoby%2Fmirror-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoby%2Fmirror-mcp/lists"}